@certivu/sdk 1.0.0 → 1.4.1

package/README.md

@@ -22,15 +22,14 @@ import { CertivuClient } from '@certivu/sdk'
 const certivu = new CertivuClient({
   apiKey: 'ctv_key_abc123',
   generatorId: 'gen_xyz',
-  privateKey: '<base64-encoded ML-DSA private key>',
 })
 
-// Sign AI-generated content
-const { token } = await certivu.sign({
-  content: imageBuffer,   // Buffer, Uint8Array, or string
+// Sign AI-generated content — returns the watermarked image + token
+const { token, record_id, watermarkedContent } = await certivu.sign({
+  content: imageBuffer,   // Buffer or Uint8Array
   model: 'stable-diffusion-xl',
 })
-// Embed `token` in XMP metadata or pass alongside content for verification
+// watermarkedContent is a Uint8Array — store and serve this, not the original
 
 // Verify — token optional, extracted automatically from XMP or watermark
 const result = await certivu.verify({ content: imageBuffer })
@@ -52,36 +51,33 @@ Get your API key and generator credentials at [dashboard.certivu.ai](https://das
 |---|---|---|---|
 | `apiKey` | `string` | Yes | API key from the dashboard (`ctv_key_...`) |
 | `generatorId` | `string` | No | Default generator ID for sign calls |
-| `privateKey` | `string` | No | Base64-encoded ML-DSA private key for sign calls |
 | `baseUrl` | `string` | No | Override API base URL (default: `https://api.certivu.ai`) |
 
 ---
 
 ### `certivu.sign(input)`
 
-Signs AI-generated content and stores a provenance record.
+Signs AI-generated content server-side — watermarking, hashing, and ML-DSA signing all happen in the API. Returns the signed, watermarked image.
 
 ```typescript
-const { token, record_id } = await certivu.sign({
-  content: imageBuffer,            // Uint8Array | string
+const { token, record_id, watermarkedContent } = await certivu.sign({
+  content: imageBuffer,            // Uint8Array | Buffer
   model: 'stable-diffusion-xl',   // model identifier
   generatorId: 'gen_xyz',         // overrides config.generatorId
-  privateKey: '...',              // overrides config.privateKey
 })
+// watermarkedContent — Uint8Array with ctv_ token in XMP + DCT watermark embedded
 ```
 
-Returns `{ token: string, record_id: string }`. Embed the `token` in XMP metadata or store it alongside the content.
-
 ---
 
 ### `certivu.verify(input)`
 
-Verifies content authenticity. Token is optional — Certivu extracts it automatically from XMP metadata or the frequency-domain watermark.
+Verifies content authenticity. Token is optional — extracted automatically from XMP metadata or the frequency-domain watermark.
 
 ```typescript
 const result = await certivu.verify({
-  content: imageBuffer,   // Uint8Array | string
-  token: 'ctv_...',      // optional — skip to let Certivu extract it
+  content: imageBuffer,   // Uint8Array | Buffer
+  token: 'ctv_...',      // optional
 })
 ```
 
@@ -103,20 +99,18 @@ const result = await certivu.verify({
     model: string,
     signed_at: string,
   } | null,
-  reason?: string,   // present when authentic: false
+  reason?: string,
 }
 ```
 
-**Confidence levels:**
-
 | Confidence | Meaning |
 |---|---|
 | `high` | Watermark + record + signature all valid |
-| `medium` | Record + signature valid, no watermark (e.g. re-uploaded without it) |
-| `low` | Partial signals — something is off |
-| `none` | No provenance data found — no claim either way |
+| `medium` | Record + signature valid, no watermark |
+| `low` | Partial signals |
+| `none` | No provenance found — no claim either way |
 
-> Absence of provenance does **not** imply human origin. Certivu verifies declared provenance; it does not detect all AI content.
+> Absence of provenance does **not** imply human origin.
 
 ---
 
@@ -127,51 +121,102 @@ Verify up to 50 items in a single request.
 ```typescript
 const { results } = await certivu.verifyBatch([
   { content: image1, token: token1 },
-  { content: image2 },             // token optional per item
+  { content: image2 },
 ])
-
-for (const result of results) {
-  console.log(result.authentic, result.confidence)
-}
 ```
 
 ---
 
 ### `certivu.getAuditLog(options?)`
 
-Fetch a paginated audit log of sign, verify, and key events for your org.
+```typescript
+const { events, total } = await certivu.getAuditLog({ page: 1, limit: 50 })
+```
+
+---
+
+### `certivu.getTokenStatus(token)`
+
+Lightweight CDN-cacheable status lookup — no image upload needed.
 
 ```typescript
-const { events, total, page, limit } = await certivu.getAuditLog({
-  page: 1,
-  limit: 50,
+const status = await certivu.getTokenStatus('ctv_7f3kx9mq2...')
+// { generator_status: 'active' | 'revoked', model, signed_at, org_id }
+```
+
+---
+
+### `certivu.getAnalyticsOverview(days?)`
+
+Verification analytics summary. Plan-gated: Free = 7-day, Starter = 30-day, Growth+ = 90-day.
+
+```typescript
+const overview = await certivu.getAnalyticsOverview(30)
+// { total_verifications, tamper_count, authentic_count, daily_trend, top_records, period_days }
+```
+
+---
+
+### `certivu.getRecordAnalytics(recordId)`
+
+Per-record verification drill-down. Growth+ required.
+
+```typescript
+const record = await certivu.getRecordAnalytics('rec-uuid')
+// { confidence_breakdown: { high, medium, low, none }, recent_events, ... }
+```
+
+---
+
+### `certivu.listWebhooks()`
+
+```typescript
+const { endpoints, webhooks_enabled } = await certivu.listWebhooks()
+```
+
+---
+
+### `certivu.createWebhook(input)`
+
+Register a new HTTPS endpoint. Growth+ required. The `secret` in the response is shown **once**.
+
+```typescript
+const endpoint = await certivu.createWebhook({
+  url: 'https://your-app.example.com/certivu',
+  events: ['record.created', 'verify.tamper_detected', 'quota.warning'],
 })
 ```
 
 ---
 
-## Error handling
+### `certivu.deleteWebhook(webhookId)`
 
-All methods throw an `Error` with a descriptive message on API or network failure.
+```typescript
+await certivu.deleteWebhook('webhook-uuid')
+```
+
+---
+
+## Error handling
 
 ```typescript
 try {
   await certivu.sign({ content, model: 'sdxl' })
 } catch (e) {
   if (e instanceof Error) {
-    console.error(e.message)  // e.g. "signature_limit_reached"
+    console.error(e.message)
   }
 }
 ```
 
-Common error codes:
-
-| Code | Meaning |
+| Status | Meaning |
 |---|---|
-| `signature_limit_reached` | Free plan 500/mo limit hit — upgrade at certivu.ai/pricing |
-| `generator_not_found` | `generatorId` doesn't exist or belongs to another org |
-| `generator_revoked` | Generator has been revoked — all its signatures are invalid |
-| `invalid_api_key` | API key is missing, malformed, or revoked |
+| `400` | Validation error |
+| `401` | Bad API key |
+| `402` | Quota exhausted (free tier) |
+| `403` | Generator doesn't belong to your org |
+| `404` | Generator not found or revoked |
+| `413` | Upload exceeds 20 MB limit |
 
 ---
 

package/dist/client.d.ts

@@ -1,14 +1,21 @@
 import type { VerificationResult } from "@certivu/types";
-import type { AuditOptions, AuditPage, BatchItem, BatchVerifyResponse, ClientConfig, SignInput, SignResponse, VerifyInput } from "./types/options";
+import type { AnalyticsOverview, AuditOptions, AuditPage, BatchItem, BatchVerifyResponse, ClientConfig, CreateWebhookInput, RecordAnalytics, SignInput, SignResponse, TokenStatus, VerifyInput, WebhookEndpoint, WebhookListResponse } from "./types/options";
 export declare class CertivuClient {
     private readonly apiKey;
     private readonly baseUrl;
     private readonly generatorId;
-    private readonly privateKey;
     constructor(config: ClientConfig);
     sign(input: SignInput): Promise<SignResponse>;
     verify(input: VerifyInput): Promise<VerificationResult>;
     verifyBatch(items: BatchItem[]): Promise<BatchVerifyResponse>;
     getAuditLog(options?: AuditOptions): Promise<AuditPage>;
+    getTokenStatus(token: string): Promise<TokenStatus>;
+    getAnalyticsOverview(days?: number): Promise<AnalyticsOverview>;
+    getRecordAnalytics(recordId: string): Promise<RecordAnalytics>;
+    listWebhooks(): Promise<WebhookListResponse>;
+    createWebhook(input: CreateWebhookInput): Promise<WebhookEndpoint & {
+        secret: string;
+    }>;
+    deleteWebhook(webhookId: string): Promise<void>;
 }
 //# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AAIzD,OAAO,KAAK,EACV,YAAY,EACZ,SAAS,EACT,SAAS,EACT,mBAAmB,EACnB,YAAY,EACZ,SAAS,EACT,YAAY,EACZ,WAAW,EACZ,MAAM,iBAAiB,CAAC;AAEzB,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAqB;IACjD,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAqB;gBAEpC,MAAM,EAAE,YAAY;IAO1B,IAAI,CAAC,KAAK,EAAE,SAAS,GAAG,OAAO,CAAC,YAAY,CAAC;IAU7C,MAAM,CAAC,KAAK,EAAE,WAAW,GAAG,OAAO,CAAC,kBAAkB,CAAC;IAIvD,WAAW,CAAC,KAAK,EAAE,SAAS,EAAE,GAAG,OAAO,CAAC,mBAAmB,CAAC;IAI7D,WAAW,CAAC,OAAO,CAAC,EAAE,YAAY,GAAG,OAAO,CAAC,SAAS,CAAC;CAG9D"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AAIzD,OAAO,KAAK,EACV,iBAAiB,EACjB,YAAY,EACZ,SAAS,EACT,SAAS,EACT,mBAAmB,EACnB,YAAY,EACZ,kBAAkB,EAClB,eAAe,EACf,SAAS,EACT,YAAY,EACZ,WAAW,EACX,WAAW,EACX,eAAe,EACf,mBAAmB,EACpB,MAAM,iBAAiB,CAAC;AAEzB,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAqB;gBAErC,MAAM,EAAE,YAAY;IAM1B,IAAI,CAAC,KAAK,EAAE,SAAS,GAAG,OAAO,CAAC,YAAY,CAAC;IAM7C,MAAM,CAAC,KAAK,EAAE,WAAW,GAAG,OAAO,CAAC,kBAAkB,CAAC;IAIvD,WAAW,CAAC,KAAK,EAAE,SAAS,EAAE,GAAG,OAAO,CAAC,mBAAmB,CAAC;IAI7D,WAAW,CAAC,OAAO,CAAC,EAAE,YAAY,GAAG,OAAO,CAAC,SAAS,CAAC;IAIvD,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC;IASnD,oBAAoB,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,CAAC;IAW/D,kBAAkB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC;IAW9D,YAAY,IAAI,OAAO,CAAC,mBAAmB,CAAC;IAW5C,aAAa,CAAC,KAAK,EAAE,kBAAkB,GAAG,OAAO,CAAC,eAAe,GAAG;QAAE,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IAavF,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAUtD"}

package/dist/index.d.ts

@@ -1,4 +1,4 @@
 export { CertivuClient } from "./client";
-export type { AuditOptions, AuditPage, BatchItem, BatchVerifyResponse, ClientConfig, SignInput, SignResponse, VerifyInput, } from "./types/options";
+export type { AuditOptions, AuditPage, BatchItem, BatchVerifyResponse, ClientConfig, SignInput, SignResponse, TokenStatus, VerifyInput, } from "./types/options";
 export type { AuditEvent, VerificationResult } from "@certivu/types";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,YAAY,EACV,YAAY,EACZ,SAAS,EACT,SAAS,EACT,mBAAmB,EACnB,YAAY,EACZ,SAAS,EACT,YAAY,EACZ,WAAW,GACZ,MAAM,iBAAiB,CAAC;AACzB,YAAY,EAAE,UAAU,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,YAAY,EACV,YAAY,EACZ,SAAS,EACT,SAAS,EACT,mBAAmB,EACnB,YAAY,EACZ,SAAS,EACT,YAAY,EACZ,WAAW,EACX,WAAW,GACZ,MAAM,iBAAiB,CAAC;AACzB,YAAY,EAAE,UAAU,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC"}