@nohead/sdk 0.8.0 → 0.10.0

package/dist/resources/drafts.d.ts

@@ -1,5 +1,5 @@
 import type { APIPromise, PagePromise } from "../api-promise.ts";
-import type { ConditionalRequestOptions, ConditionalWriteOptions, RequestOptions } from "../core.ts";
+import type { ConditionalRequestOptions, ConditionalWriteOptions, RichTextOptions } from "../core.ts";
 import type { RecordData } from "../generated/types.gen.ts";
 import type { DraftCreateParams, DraftGetParams, DraftListParams, DraftScheduleParams, DraftUpdateParams, NoheadDraft, NoheadRecord } from "../types.ts";
 import { Resource } from "./resource.ts";
@@ -17,24 +17,24 @@ export declare class Drafts extends Resource {
      * `ConflictError` (detail code `draft_exists`, with its `draft_id`): update
      * that one instead.
      */
-    create<D = RecordData>(record: string, params?: DraftCreateParams<D>, options?: RequestOptions): APIPromise<NoheadDraft<D>>;
+    create<D = RecordData>(record: string, params?: DraftCreateParams<D>, options?: RichTextOptions): APIPromise<NoheadDraft<D>>;
     /**
      * A collection's drafts, most recently changed first. One record's draft
      * is `records.drafts(record)`.
      */
-    list<D = RecordData>(collection: string, params?: DraftListParams, options?: RequestOptions): PagePromise<NoheadDraft<D>>;
+    list<D = RecordData>(collection: string, params?: DraftListParams, options?: RichTextOptions): PagePromise<NoheadDraft<D>>;
     /** With `data` as the record reads after the merge, for previews. */
-    get<D = RecordData>(draft: string, params?: DraftGetParams, options?: RequestOptions): APIPromise<NoheadDraft<D>>;
+    get<D = RecordData>(draft: string, params?: DraftGetParams, options?: RichTextOptions): APIPromise<NoheadDraft<D>>;
     /** Sets the given fields (`null` clears one), as a record update does. */
-    update<D = RecordData>(draft: string, params: DraftUpdateParams<D>, options?: ConditionalRequestOptions): APIPromise<NoheadDraft<D>>;
+    update<D = RecordData>(draft: string, params: DraftUpdateParams<D>, options?: ConditionalRequestOptions & RichTextOptions): APIPromise<NoheadDraft<D>>;
     /** Deletes the draft for good; returns it as it was. */
-    discard<D = RecordData>(draft: string, options?: ConditionalRequestOptions): APIPromise<NoheadDraft<D>>;
+    discard<D = RecordData>(draft: string, options?: ConditionalRequestOptions & RichTextOptions): APIPromise<NoheadDraft<D>>;
     /**
      * Applies the draft to its record now, as one `merge` revision, and
      * returns the record. Content only: the record stays live or not.
      */
-    merge<D = RecordData>(draft: string, options?: ConditionalWriteOptions): APIPromise<NoheadRecord<D>>;
+    merge<D = RecordData>(draft: string, options?: ConditionalWriteOptions & RichTextOptions): APIPromise<NoheadRecord<D>>;
     /** Merges the draft at `merge_at`, a future time; returns the draft. */
-    schedule<D = RecordData>(draft: string, params: DraftScheduleParams, options?: RequestOptions): APIPromise<NoheadDraft<D>>;
-    unschedule<D = RecordData>(draft: string, options?: RequestOptions): APIPromise<NoheadDraft<D>>;
+    schedule<D = RecordData>(draft: string, params: DraftScheduleParams, options?: RichTextOptions): APIPromise<NoheadDraft<D>>;
+    unschedule<D = RecordData>(draft: string, options?: RichTextOptions): APIPromise<NoheadDraft<D>>;
 }

package/dist/resources/records.d.ts

@@ -1,5 +1,5 @@
 import type { APIPromise, PagePromise } from "../api-promise.ts";
-import type { ConditionalWriteOptions, RequestOptions, WriteOptions } from "../core.ts";
+import type { ConditionalWriteOptions, RequestOptions, RichTextOptions, WriteOptions } from "../core.ts";
 import type { RecordData, RecordDiff, RecordRevision, RecordRevisionDetail, RevertPreview, RecordBatch, RecordCount, RecordPublication, RecordSchedule, ScheduledChange } from "../generated/types.gen.ts";
 import type { DryRunParams, NoheadDraft, NoheadRecord, RecordBulkParams, RecordCountParams, RecordCreateParams, RecordDiffParams, RecordGetParams, RecordListParams, RecordScheduleParams, RecordSearchParams, RecordUpdateParams, ListParams, RevisionListParams, ScheduledChangeListParams, SearchMeta } from "../types.ts";
 import { Resource } from "./resource.ts";
@@ -10,28 +10,28 @@ import { Resource } from "./resource.ts";
 export declare class Records extends Resource {
     readonly revisions: Revisions;
     /** A collection's records, newest first by default. */
-    list<D = RecordData>(collection: string, params?: RecordListParams, options?: RequestOptions): PagePromise<NoheadRecord<D>>;
-    get<D = RecordData>(record: string, params?: RecordGetParams, options?: RequestOptions): APIPromise<NoheadRecord<D>>;
+    list<D = RecordData>(collection: string, params?: RecordListParams, options?: RichTextOptions): PagePromise<NoheadRecord<D>>;
+    get<D = RecordData>(record: string, params?: RecordGetParams, options?: RichTextOptions): APIPromise<NoheadRecord<D>>;
     /**
      * Creates an unpublished record. With `upsert_on`, updates the record
      * holding that unique value instead, if one exists, so a sync can run
      * again without duplicates; `ifMatch` then applies to that update.
      */
-    create<D = RecordData>(collection: string, params: RecordCreateParams<D>, options?: ConditionalWriteOptions): APIPromise<NoheadRecord<D>>;
+    create<D = RecordData>(collection: string, params: RecordCreateParams<D>, options?: ConditionalWriteOptions & RichTextOptions): APIPromise<NoheadRecord<D>>;
     /** Sets the given fields (`null` clears one); others keep their values. */
-    update<D = RecordData>(record: string, params: RecordUpdateParams<D>, options?: ConditionalWriteOptions): APIPromise<NoheadRecord<D>>;
+    update<D = RecordData>(record: string, params: RecordUpdateParams<D>, options?: ConditionalWriteOptions & RichTextOptions): APIPromise<NoheadRecord<D>>;
     /**
      * Soft-deletes the record: `restore` brings it back until its
      * `purge_after`. Deleting a deleted record changes nothing.
      */
-    delete<D = RecordData>(record: string, options?: ConditionalWriteOptions): APIPromise<NoheadRecord<D>>;
-    restore<D = RecordData>(record: string, options?: ConditionalWriteOptions): APIPromise<NoheadRecord<D>>;
+    delete<D = RecordData>(record: string, options?: ConditionalWriteOptions & RichTextOptions): APIPromise<NoheadRecord<D>>;
+    restore<D = RecordData>(record: string, options?: ConditionalWriteOptions & RichTextOptions): APIPromise<NoheadRecord<D>>;
     /**
      * A live record with a pending draft is a `ConflictError` (detail code
      * `draft_pending`): publishing never merges a draft (`drafts.merge` does).
      */
-    publish<D = RecordData>(record: string, options?: ConditionalWriteOptions): APIPromise<NoheadRecord<D>>;
-    unpublish<D = RecordData>(record: string, options?: ConditionalWriteOptions): APIPromise<NoheadRecord<D>>;
+    publish<D = RecordData>(record: string, options?: ConditionalWriteOptions & RichTextOptions): APIPromise<NoheadRecord<D>>;
+    unpublish<D = RecordData>(record: string, options?: ConditionalWriteOptions & RichTextOptions): APIPromise<NoheadRecord<D>>;
     /**
      * What is live: since when, by whom, and the revision. A record that
      * isn't published is a `NotFoundError` (detail code `not_published`).
@@ -43,7 +43,7 @@ export declare class Records extends Resource {
      */
     getSchedule(record: string, options?: RequestOptions): APIPromise<RecordSchedule>;
     /** The record's drafts: at most one for now. */
-    drafts<D = RecordData>(record: string, params?: ListParams, options?: RequestOptions): PagePromise<NoheadDraft<D>>;
+    drafts<D = RecordData>(record: string, params?: ListParams, options?: RichTextOptions): PagePromise<NoheadDraft<D>>;
     /**
      * Sets when the record publishes and unpublishes on its own. This is the
      * whole schedule: a time left out is cleared (`{}` clears both, as
@@ -63,14 +63,14 @@ export declare class Records extends Resource {
      * Publishes, unpublishes, deletes, restores or updates up to 100 records.
      * Each record succeeds or fails on its own; see `results`.
      */
-    bulk(collection: string, params: RecordBulkParams, options?: WriteOptions): APIPromise<RecordBatch>;
+    bulk(collection: string, params: RecordBulkParams, options?: WriteOptions & RichTextOptions): APIPromise<RecordBatch>;
     /** The changes between two revisions. */
     diff(record: string, params: RecordDiffParams, options?: RequestOptions): APIPromise<RecordDiff>;
     /**
      * Full-text search in one collection, matching its `searchable` fields.
      * Pages through the first 1,000 hits, most relevant first.
      */
-    search<D = RecordData>(collection: string, query: string, params?: RecordSearchParams, options?: RequestOptions): PagePromise<NoheadRecord<D>, SearchMeta>;
+    search<D = RecordData>(collection: string, query: string, params?: RecordSearchParams, options?: RichTextOptions): PagePromise<NoheadRecord<D>, SearchMeta>;
 }
 /** A record's version history. `revision` is a revision number. */
 export declare class Revisions extends Resource {
@@ -80,8 +80,8 @@ export declare class Revisions extends Resource {
     /** Restores the record's data as of `revision`, as a new revision. */
     revert(record: string, revision: number, params: {
         dry_run: true;
-    }, options?: ConditionalWriteOptions): APIPromise<RevertPreview>;
-    revert<D = RecordData>(record: string, revision: number, params?: DryRunParams, options?: ConditionalWriteOptions): APIPromise<NoheadRecord<D>>;
+    }, options?: ConditionalWriteOptions & RichTextOptions): APIPromise<RevertPreview>;
+    revert<D = RecordData>(record: string, revision: number, params?: DryRunParams, options?: ConditionalWriteOptions & RichTextOptions): APIPromise<NoheadRecord<D>>;
 }
 /**
  * A revision by its own ID (`rev_…`), as webhooks and the activity log name

package/dist/types.d.ts

@@ -21,6 +21,13 @@ export type NoheadDraft<D = G.RecordData> = Omit<G.Draft, "data"> & {
 export type RecordDataUpdate<D> = {
     [K in keyof D]?: D[K] | null;
 };
+/**
+ * How rich text fields read (`richText`): `"document"`, the stored
+ * ProseMirror JSON document (the default); `"html"`, an HTML fragment safe
+ * to put in a page as it is; or `"markdown"` (GitHub Flavored). As HTML or
+ * Markdown, a rich text field's value is a string.
+ */
+export type RichText = G.RichText;
 export type FilterValue = string | number | boolean | Date;
 /**
  * Operators for one key. `ne` matches records without a value; on fields

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const VERSION = "0.8.0";
+export declare const VERSION = "0.10.0";

package/dist/version.js

@@ -1 +1 @@
-export const VERSION = "0.8.0";
+export const VERSION = "0.10.0";

package/dist/webhooks.d.ts

@@ -49,8 +49,9 @@ export interface UnwrapOptions {
     /**
      * The webhook's signing secret (`whsec_…`). While a rotation overlaps,
      * requests carry a signature for each secret, so either one verifies.
+     * An unset one (as from a missing environment variable) throws.
      */
-    secret: string;
+    secret: string | undefined;
     /** Seconds a timestamp may be off from now. Default 300. */
     tolerance?: number;
 }

package/dist/webhooks.js

@@ -24,7 +24,11 @@ export async function unwrapWebhook(body, headers, { secret, tolerance = 300 })
         throw new WebhookVerificationError("The webhook timestamp is too far from the current time");
     }
     const text = typeof body === "string" ? body : new TextDecoder().decode(body);
-    const key = await crypto.subtle.importKey("raw", decodeBase64(secret.replace(/^whsec_/, ""), "secret"), { name: "HMAC", hash: "SHA-256" }, false, ["verify"]);
+    const keyBytes = decodeBase64((secret ?? "").replace(/^whsec_/, ""), "secret");
+    if (keyBytes.length === 0) {
+        throw new WebhookVerificationError("The webhook secret is empty");
+    }
+    const key = await crypto.subtle.importKey("raw", keyBytes, { name: "HMAC", hash: "SHA-256" }, false, ["verify"]);
     const signed = new TextEncoder().encode(`${id}.${timestamp}.${text}`);
     for (const entry of signatures.split(" ")) {
         const [version, signature] = entry.split(",", 2);
@@ -63,8 +67,5 @@ function decodeBase64(value, what) {
     catch {
         throw new WebhookVerificationError(`The webhook ${what} is not base64`);
     }
-    const bytes = new Uint8Array(binary.length);
-    for (let i = 0; i < binary.length; i++)
-        bytes[i] = binary.charCodeAt(i);
-    return bytes;
+    return Uint8Array.from(binary, (char) => char.charCodeAt(0));
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nohead/sdk",
-  "version": "0.8.0",
+  "version": "0.10.0",
   "description": "Official TypeScript SDK for the Nohead API",
   "license": "MIT",
   "homepage": "https://nohead.io",
@@ -61,6 +61,7 @@
     "eslint": "^10.12.0",
     "globals": "^17.13.0",
     "prettier": "^3.9.9",
+    "standardwebhooks": "^1.1.1",
     "typescript": "^6.0.3",
     "typescript-eslint": "^8.71.0",
     "vitest": "^5.0.3"