# RHypernova All-in-One PDF Editor API Integration

This document is for fintech and document organizations that want to use RHypernova PDF editing inside their own application with one token and one API contract.

## Product Contract

- UI embed SDK: `GET https://api.rhypernova.com/api/v1/pdf/embed.js`
- Main PDF API: `POST https://api.rhypernova.com/api/v1/pdf/run`
- Usage API: `GET https://api.rhypernova.com/api/v1/pdf/usage`
- Features API: `GET https://api.rhypernova.com/api/v1/pdf/features`
- Token header: `Authorization: Bearer ORG_TOKEN`
- Optional token header: `X-RHypernova-PDF-Token: ORG_TOKEN`
- UI mount div: `<div id="allinonepdf"></div>`
- Embedded editor route: `/pdf/embed`
- Studio route: `/pdf/edit`
- Optional new-tab fallback label: `data-open-label="Open PDF Editor in new tab"`
- Optional fallback disable flag: `data-open-link="false"`

The embed SDK opens the **full PDF editor workspace** (upload, edit document, PDF tools, draw studio). One-shot server actions are selected by `tool_key`, for example `compress`, `merge`, `split`, `protect`, `sign`, `pdf_to_text`, or `images_to_pdf`.

## Billing Model

1. Client buys a PDF API plan from the RHypernova API dashboard.
2. RHypernova issues an organization token after payment.
3. Client uses the token in the embedded UI or direct API calls.
4. Backend tracks usage by hashed token ID.
5. Successful `POST /run` actions are counted as billable units.
6. Billing can be calculated from `GET /api/v1/pdf/usage`.

## HTML / JavaScript Embed

```html
<div id="allinonepdf"></div>
<script
  src="https://api.rhypernova.com/api/v1/pdf/embed.js"
  data-token="ORG_TOKEN"
  data-api-base="https://api.rhypernova.com/api/v1/pdf"
  data-frontend-url="https://app.rhypernova.com"
  data-open-label="Open PDF Editor in new tab">
</script>
```

The PDF editor UI stays inside the same container where the client places `#allinonepdf`. The SDK creates an absolute iframe URL to `/pdf/embed` and adds a direct new-tab fallback link by default. It does not require the client to build PDF upload screens, Angular services, React services, or custom editing workflows.

## Embed Script Attributes

Use these attributes to tell the SDK where to mount the PDF editor UI and how to authenticate API calls:

- `src`: Loads the RHypernova embed SDK from the PDF API service.
- `data-token`: Organization token issued after payment. The SDK passes this token to PDF API calls for authentication and usage billing.
- `data-api-base`: Base URL of the PDF API, for example `https://api.rhypernova.com/api/v1/pdf`.
- `data-frontend-url`: Base URL of the RHypernova frontend that hosts the embedded PDF editor screen.
- `data-open-label`: Optional text for the fallback link under the iframe. Example: `Open PDF Editor in new tab`.
- `data-open-link`: Optional flag to hide the fallback link. Set `data-open-link="false"` only if the client does not want the new-tab option.
- `data-theme`: Optional UI theme hint passed to the embedded frame (`light` or `dark`).
- `data-client-id`: Optional label shown in the embed header for support and audit context.

## Embedded Editor vs Direct API

| Use case | Recommended approach |
|----------|---------------------|
| Full PDF editing inside client app | Embed SDK → `/pdf/embed` |
| Server-to-server compress, merge, convert | `POST /run` with `tool_key` |
| Live preview, text editing, draw studio | Session APIs via embedded editor |
| Billing and usage analytics | `GET /usage` |

The embedded editor uses session and editable endpoints (`/session/*`, `/editable/*`) for interactive workflows. The unified `POST /run` contract is optimized for one-shot PDF actions from backend automation.

## React Embed

```tsx
useEffect(() => {
  const s = document.createElement('script');
  s.src = 'https://api.rhypernova.com/api/v1/pdf/embed.js';
  s.dataset.token = 'ORG_TOKEN';
  s.dataset.apiBase = 'https://api.rhypernova.com/api/v1/pdf';
  s.dataset.frontendUrl = 'https://app.rhypernova.com';
  document.body.appendChild(s);
}, []);
return <div id="allinonepdf" />;
```

## Angular Embed

```ts
ngAfterViewInit() {
  const s = document.createElement('script');
  s.src = 'https://api.rhypernova.com/api/v1/pdf/embed.js';
  s.dataset['token'] = 'ORG_TOKEN';
  s.dataset['apiBase'] = 'https://api.rhypernova.com/api/v1/pdf';
  s.dataset['frontendUrl'] = 'https://app.rhypernova.com';
  document.body.appendChild(s);
}
```

```html
<div id="allinonepdf"></div>
```

## Vue Embed

```vue
<template><div id="allinonepdf"></div></template>
<script setup>
import { onMounted } from 'vue';
onMounted(() => {
  const s = document.createElement('script');
  s.src = 'https://api.rhypernova.com/api/v1/pdf/embed.js';
  s.dataset.token = 'ORG_TOKEN';
  s.dataset.apiBase = 'https://api.rhypernova.com/api/v1/pdf';
  document.body.appendChild(s);
});
</script>
```

## Angular Direct Iframe Note

Use the SDK snippet above for Angular apps whenever possible. If a client chooses to bind the PDF frame URL directly to an Angular `<iframe [src]>`, Angular requires a trusted resource URL:

```ts
constructor(private sanitizer: DomSanitizer) {}

safeFrameUrl = this.sanitizer.bypassSecurityTrustResourceUrl(
  'https://app.rhypernova.com/pdf/embed?apiBase=https%3A%2F%2Fapi.rhypernova.com%2Fapi%2Fv1%2Fpdf&token=ORG_TOKEN'
);
```

```html
<iframe [src]="safeFrameUrl" title="RHypernova PDF Editor"></iframe>
```

Without this sanitizer step, Angular may show a blank iframe even though opening the same URL in a new browser tab works.

## Direct API: Python

```python
import requests

files = {"file": open("contract.pdf", "rb")}
data = {"tool_key": "compress", "quality": "85"}
headers = {"Authorization": "Bearer ORG_TOKEN"}
res = requests.post("https://api.rhypernova.com/api/v1/pdf/run", files=files, data=data, headers=headers)
with open("compressed.pdf", "wb") as f:
    f.write(res.content)
```

## Direct API: JavaScript

```js
const form = new FormData();
form.append('tool_key', 'merge');
selectedFiles.forEach(file => form.append('files', file));
const res = await fetch('https://api.rhypernova.com/api/v1/pdf/run', {
  method: 'POST',
  headers: { Authorization: 'Bearer ORG_TOKEN' },
  body: form
});
const blob = await res.blob();
```

## Direct API: Java

```java
HttpRequest request = HttpRequest.newBuilder()
  .uri(URI.create("https://api.rhypernova.com/api/v1/pdf/usage"))
  .header("Authorization", "Bearer ORG_TOKEN")
  .GET()
  .build();
HttpResponse<String> res = HttpClient.newHttpClient().send(request, BodyHandlers.ofString());
System.out.println(res.body());
```

## Direct API: .NET

```csharp
using var client = new HttpClient();
client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", "ORG_TOKEN");
using var form = new MultipartFormDataContent();
form.Add(new StringContent("protect"), "tool_key");
form.Add(new StringContent("secret123"), "password");
form.Add(new StreamContent(File.OpenRead("report.pdf")), "file", "report.pdf");
var res = await client.PostAsync("https://api.rhypernova.com/api/v1/pdf/run", form);
await File.WriteAllBytesAsync("protected.pdf", await res.Content.ReadAsByteArrayAsync());
```

## Supported `tool_key` Values

One-shot tools available through `POST /run`:

- **Basic:** `resize`, `crop`, `rotate`, `split`, `merge`
- **Edit:** `edit_text`, `add_image`, `annotate`, `watermark`, `header_footer`
- **Security:** `compress`, `protect`, `unlock`, `redact`, `repair`
- **Organize:** `delete_pages`, `extract_pages`, `reorder_pages`, `duplicate_pages`, `insert_blank_page`, `page_numbers`
- **Document:** `flatten`, `stamp`, `sign`, `remove_metadata`
- **Convert:** `pdf_to_images`, `images_to_pdf`, `pdf_to_text`, `text_to_pdf`, `pdf_to_html`, `extract_images`

Interactive studio features (`draw`, rich text editing, live session preview) are available through the embedded editor at `/pdf/embed`, not through `POST /run`.

## Usage Check

```bash
curl -H "Authorization: Bearer ORG_TOKEN" \
  https://api.rhypernova.com/api/v1/pdf/usage
```

## Features Discovery

```bash
curl https://api.rhypernova.com/api/v1/pdf/features
```

## Recommended Client Flow

- Use embedded UI when the client wants a ready PDF editor inside their product.
- Use `POST /run` directly when the client wants server-to-server PDF automation (compress, merge, convert, protect, etc.).
- Use `GET /usage` for billing, usage analytics, and invoice reconciliation.
- Use `GET /features` for API discovery and integration tooling.
- Rotate tokens per organization and per environment (`sandbox`, `production`).

## Internal QA

Before selling API access, validate the embed contract on:

- `/pdf/api-self-test` — live iframe + SDK snippet checklist
- `/pdf/api-business` — token generation and buyer journey preview