@calmlens/sdk 0.16.2 → 0.17.1

package/esm/CalmLensServerClient-JtP687a3.d.ts

@@ -0,0 +1,235 @@
+import { o as HashList, s as HashListEntry } from "./ModerationContext-9lGm-Mna-CcmbRnOy.js";
+import { $ as IterateAssetsOptions, A as ClassifyTextOptions, B as EnsureLensesOptions, C as BatchAssetsResponse, Ct as UploadAssetPartOptions, E as CdnAssetUrlOptions, Et as VerifyWebhookSignatureOptions, G as HashListEntryIdOptions, H as FolderIdOptions, I as DecideAssetOptions, J as HashListPage, Jt as AssetSearchQuery, K as HashListEntryPage, L as DeleteAssetContentOptions, M as CreateAssetSignedUrlOptions, Mt as GetEventsResponse, N as CreateFolderOptions, Nt as PostAssetSignedUrlResponse, O as CdnServeOptions, Ot as WaitForAssetDecisionOptions, P as CreateHashListOptions, Q as IterateAssetChildrenOptions, R as DeleteAssetOptions, S as BatchAssetsOptions, St as UpdateHashListOptions, T as CalmLensServerClientOptions, U as FolderPage, Ut as Folder, V as ExplainAssetOptions, _t as SignedUploadToken, at as ListFoldersOptions, bt as UpdateAssetOptions, ct as MoveAssetOptions, et as Lens, ft as RequestOptions, g as AssetSearchResponse, gt as SignUploadTokenOptions, h as AssetPage, i as AssetChildrenPage, it as ListEventsOptions, lt as MoveFolderOptions, mt as RetryAssetOptions, n as Asset, nt as ListAssetChildrenOptions, ot as ListHashListEntriesOptions, pt as RetrieveAssetOptions, q as HashListIdOptions, rt as ListAssetsOptions, st as ListHashListsOptions, t as AddHashListEntryOptions, xt as UpdateFolderOptions, yt as SubmitAssetOptions, z as EnsureLensOptions } from "./CalmLensTypes-9Vt16pc7.js";
+import "./WebhookPayload-2aL31v0J.js";
+interface LensCache {
+  readonly ensuredLenses: Map<string, Lens>;
+  readonly pendingEnsureLenses: Map<string, Promise<void>>;
+}
+declare const inspectSymbol: unique symbol;
+/**
+ * The CalmLens API client for your server, authenticated with a project API key. Create one per
+ * project and reuse it; it holds no connections. Every method takes one options object and
+ * throws `CalmLensError` on failure. Browsers and apps upload with `CalmLensAppClient` instead.
+ */
+declare class CalmLensServerClient {
+  #private;
+  /**
+   * Verifies that a webhook delivery came from CalmLens: checks the `v1=` HMAC-SHA256 in
+   * `x-calmlens-signature` over `"<x-calmlens-timestamp>.<raw body>"` and rejects timestamps
+   * more than `toleranceSeconds` (default 300) from now, which stops replayed deliveries.
+   * Also exported as `verifyWebhookSignature`; `parseWebhookEvent` verifies and parses.
+   *
+   * @example
+   * ```ts
+   * const payload = await request.text();
+   * const isValid = await CalmLensServerClient.verifyWebhookSignature({
+   *   payload,
+   *   headers: request.headers,
+   *   secret: process.env.CALMLENS_WEBHOOK_SECRET!,
+   * });
+   * ```
+   */
+  static verifyWebhookSignature(options: VerifyWebhookSignatureOptions): Promise<boolean>;
+  constructor(options: CalmLensServerClientOptions, lenses?: LensCache);
+  /**
+   * A client with different cancellation, deadlines or retries for the calls made through it,
+   * sharing this client's credentials and lens cache. This client is unchanged.
+   */
+  withRequestOptions(options: RequestOptions): CalmLensServerClient;
+  /** Keeps the API key out of `console.log`, `util.inspect` and `JSON.stringify`. */
+  [inspectSymbol](): string;
+  toJSON(): {
+    projectId: string;
+    baseUrl: string;
+    cdnBaseUrl: string;
+  };
+  private get projectPath();
+  private request;
+  private submitAsset;
+  get cdn(): {
+    /**
+     * Builds a CDN URL for asset content or a preview, without a request. Private assets
+     * need a signed URL (`assets.createSignedUrl`) or an authenticated request; public
+     * age-restricted assets additionally require `viewerClaims.ageConfirmed: true`.
+     */
+    getAssetUrl: ({ assetIdentifier, ...options }: CdnAssetUrlOptions) => string;
+    /**
+     * Fetches asset content or a preview from the CDN with the client's API key, and returns
+     * the `Response` as soon as headers arrive, so the body streams. Non-2xx responses are
+     * returned, not thrown; `timeoutMs` covers only the wait for headers.
+     */
+    serve: ({ assetIdentifier, init, ...urlOptions }: CdnServeOptions) => Promise<Response>;
+  };
+  get text(): {
+    /**
+     * Moderates text and waits for the decision. Sends `text` as `text/plain` content named
+     * `text` unless you pass `name`.
+     */
+    classify: (options: ClassifyTextOptions) => Promise<Asset>;
+  };
+  /** Assets: uploads, moderation and management. */
+  get assets(): {
+    /** Searches accessible assets by keyword or a natural-language description. */
+    search: (options: Partial<AssetSearchQuery> & {
+      query: string;
+    }) => Promise<AssetSearchResponse>;
+    /** Lists one page of the project's assets, with optional filter and ordering. */
+    list: (options?: ListAssetsOptions) => Promise<AssetPage>;
+    /**
+     * Yields every asset matching `options`, fetching pages as needed. The cursor keeps the position
+     * stable when other assets are inserted or deleted.
+     */
+    iterate: (options?: IterateAssetsOptions) => AsyncGenerator<Asset, void, undefined>;
+    /** Retrieves an asset with its status and classification results. */
+    retrieve: ({ assetId }: RetrieveAssetOptions) => Promise<Asset>;
+    /** Updates an asset's editable fields. */
+    update: ({ assetId, ...body }: UpdateAssetOptions) => Promise<Asset>;
+    /** Lists one page of the assets extracted from a website or multimedia document. */
+    listChildren: ({ assetId, ...options }?: ListAssetChildrenOptions) => Promise<AssetChildrenPage>;
+    /** Yields every child of an asset, fetching pages as needed. */
+    iterateChildren: (options: IterateAssetChildrenOptions) => AsyncGenerator<Asset, void, undefined>;
+    /**
+     * Uploads an asset and queues it for moderation, returning immediately with processing
+     * status `processing` (or `uploading` for the first multipart part). Retried safely with an
+     * `Idempotency-Key`.
+     */
+    create: (options: SubmitAssetOptions) => Promise<Asset>;
+    /**
+     * Uploads an asset and waits for its moderation decision. Audio and video still finish
+     * in the background. Retried safely with an `Idempotency-Key`.
+     */
+    classify: (options: SubmitAssetOptions) => Promise<Asset>;
+    /**
+     * Uploads the next part of a multipart upload. The upload's queue mode, chosen when it
+     * started, applies when the final part arrives; pass `queue` to override it.
+     */
+    uploadPart: ({ assetId, ...options }: UploadAssetPartOptions) => Promise<Asset>;
+    /**
+     * Creates a short-lived signed CDN URL, so browsers can load private content without
+     * an API key.
+     */
+    createSignedUrl: ({ assetId, ...options }: CreateAssetSignedUrlOptions) => Promise<PostAssetSignedUrlResponse>;
+    /** Moves an asset into a folder, or to the project root with `folderId: null`. */
+    move: ({ assetId, folderId }: MoveAssetOptions) => Promise<Asset>;
+    /**
+     * Processes an asset that failed (classification status `failed`) again. It returns to
+     * `processing` and is
+     * moderated like a new upload; its content must still be stored.
+     */
+    retry: ({ assetId }: RetryAssetOptions) => Promise<Asset>;
+    /**
+     * Records a reviewer's decision, replacing the policy's: the asset's moderation status
+     * becomes `decision`, the note joins its review history and the matching `asset.<status>`
+     * event is sent. An asset still pending moderation can only be blocked or purged. Purging
+     * needs `confirmPurge: true` and permanently deletes the stored content.
+     */
+    decide: ({ assetId, ...body }: DecideAssetOptions) => Promise<Asset>;
+    /**
+     * Completes the policy evidence behind a decided asset's moderation decision: the report's
+     * `classification.moderation.evidence` becomes `full` and every action stays as
+     * decided. With `rerun: true` the asset is moderated again with the project's current policy
+     * and returns in `processing`; use it when the policy has changed since the decision
+     * (`asset/policy-changed`).
+     */
+    explain: ({ assetId, rerun }: ExplainAssetOptions) => Promise<Asset>;
+    /**
+     * Waits until an asset's `classification.moderation.status` is no longer `pending` (`allowed`,
+     * `limited`, `age-restricted`, `blocked` or `purged`), or its `classification.status` is `failed`, and returns that asset, checking every few seconds. Rejects with `sdk/timeout` if there is no
+     * decision within `timeoutMs` (default 60000). Webhooks report decisions without polling.
+     */
+    waitForDecision: ({ assetId, ...options }: WaitForAssetDecisionOptions) => Promise<Asset>;
+    /**
+     * Removes an asset's stored content (source, preview and retained extracted text) while
+     * keeping the asset record, metadata and classification results. The returned asset has
+     * `content.status` set to `removed` and `content.removalReason` to `requested`; the CDN no longer serves it.
+     */
+    deleteContent: ({ assetId }: DeleteAssetContentOptions) => Promise<Asset>;
+    /** Deletes an asset record together with its stored content. */
+    delete: ({ assetId }: DeleteAssetOptions) => Promise<void>;
+    /**
+     * Deletes up to 500 assets (`operation: "delete"`) or removes their stored content
+     * (`"remove-content"`) in one request. Every asset must exist in the project and the key
+     * needs `assets:delete` for its folder, or nothing is queued. Resolves with
+     * `{ queued: true }` once queued; the work runs in the background and records
+     * `asset.deleted` or `asset.content-removed` for each asset. Assets under a safety hold
+     * are skipped. Not retried: it carries no `Idempotency-Key`.
+     */
+    batch: ({ assetIds, operation }: BatchAssetsOptions) => Promise<BatchAssetsResponse>;
+  };
+  /**
+   * Signs upload tokens on your server, so a browser or app can upload through an upload preset
+   * that requires one. Signing happens locally with your API key: it makes no request.
+   */
+  get uploadTokens(): {
+    /**
+     * Signs a single-use token for one upload through `uploadPresetId`. Give `token` to the
+     * browser or app, which passes it to `CalmLensAppClient` as `token`.
+     */
+    sign: (options: SignUploadTokenOptions) => Promise<SignedUploadToken>;
+  };
+  private buildAssets;
+  get events(): {
+    /**
+     * Lists project events after a cursor, oldest first. Call without `cursor` to get a cursor
+     * for "now", then poll with each response's `nextCursor`. Webhook deliveries carry the same
+     * events reshaped as `{ id, type, createdAt, projectId, data }`.
+     */
+    list: (options?: ListEventsOptions) => Promise<GetEventsResponse>;
+    /**
+     * Yields pages of events after `cursor` until no more are waiting. Save each page's
+     * `nextCursor` to resume later. Without `cursor`, yields one empty page whose `nextCursor`
+     * is "now".
+     */
+    pages: (options?: ListEventsOptions) => AsyncGenerator<GetEventsResponse, void, undefined>;
+  };
+  private iterateEventPages;
+  private iteratePages;
+  get folders(): {
+    /**
+     * Lists one page of child folders, sorted by name unless `ordering` says otherwise. Pass
+     * `nextCursor` as `cursor` for the next page; fetch a branch when it is opened.
+     */
+    list: (options?: ListFoldersOptions) => Promise<FolderPage>;
+    retrieve: ({ folderId }: FolderIdOptions) => Promise<Folder>;
+    /** Creates a folder at the project root or inside `parentId`. */
+    create: (options: CreateFolderOptions) => Promise<Folder>;
+    update: ({ folderId, ...body }: UpdateFolderOptions) => Promise<Folder>;
+    /** Deletes an empty folder; throws `folder/not-empty` otherwise. */
+    delete: ({ folderId }: FolderIdOptions) => Promise<void>;
+    /** Moves a folder under `parentId`, or to the project root with `parentId: null`. */
+    move: ({ folderId, parentId }: MoveFolderOptions) => Promise<Folder>;
+  };
+  /**
+   * Hash lists hold PDQ hashes of images the project never wants again. Image uploads are
+   * compared with every list: `flag` lists record matches, `block` lists also block close ones.
+   */
+  get hashLists(): {
+    /** Lists one page of the project's hash lists, newest first. */
+    list: (options?: ListHashListsOptions) => Promise<HashListPage>;
+    retrieve: ({ hashListId }: HashListIdOptions) => Promise<HashList>;
+    create: (options: CreateHashListOptions) => Promise<HashList>;
+    /** Renames a list or changes its action; the new action applies to later uploads. */
+    update: ({ hashListId, ...body }: UpdateHashListOptions) => Promise<HashList>;
+    /** Deletes the list and every entry in it. */
+    delete: ({ hashListId }: HashListIdOptions) => Promise<void>;
+    /** Lists one page of a list's entries, newest first. */
+    listEntries: ({ hashListId, ...query }: ListHashListEntriesOptions) => Promise<HashListEntryPage>;
+    /** Adds a hash, or an image asset's hash; a hash already in the list returns its entry. */
+    addEntry: ({ hashListId, ...body }: AddHashListEntryOptions) => Promise<HashListEntry>;
+    removeEntry: ({ entryId }: HashListEntryIdOptions) => Promise<void>;
+  };
+  /**
+   * Create a named lens at any positive version, or update it with a greater version.
+   * Supplying the same definition and version is idempotent.
+   */
+  ensureLens(options: EnsureLensOptions): Promise<Lens>;
+  /**
+   * Create or update several named lenses. New definitions are sent in one API request, or in
+   * consecutive requests of at most {@link ENSURE_LENSES_MAX_PER_REQUEST} definitions, in order.
+   * Each lens follows the same versioning and idempotency rules as ensureLens().
+   */
+  ensureLenses({ lenses }: EnsureLensesOptions): Promise<Lens[]>;
+  private submitEnsureLenses;
+  private submitEnsureLensesChunk;
+}
+export { CalmLensServerClient as t };