@nohead/sdk 0.0.0 → 0.1.0

package/dist/types.d.ts

@@ -0,0 +1,99 @@
+import type * as G from "./generated/types.gen.ts";
+export type * from "./generated/schemas.gen.ts";
+/**
+ * A record whose `data` has the shape `D`. Exported as `Nohead.Record` and
+ * `NoheadRecord`, so it never shadows TypeScript's own `Record<K, V>`.
+ *
+ *   interface Post { title: string; author: string }
+ *   const post = await nohead.records.get<Post>(id)   // post.data.title
+ */
+export type NoheadRecord<D = G.RecordData> = Omit<G.Record, "data"> & {
+    data: D;
+};
+/** Field values to write: `null` clears a field. */
+export type RecordDataUpdate<D> = {
+    [K in keyof D]?: D[K] | null;
+};
+export type FilterValue = string | number | boolean | Date;
+/**
+ * Equality filters: `{ status: "published", author: "rec_…" }`. For fields
+ * with several values a filter means "contains".
+ */
+export interface RecordFilter {
+    status?: "draft" | "published";
+    deleted?: boolean;
+    [apiKey: string]: FilterValue | undefined;
+}
+export type RecordSort = NonNullable<NonNullable<G.RecordsListData["query"]>["sort"]>;
+export interface ListParams {
+    /** Page size, 1 to 100 (default 20). */
+    limit?: number;
+    /** Start from a page's `meta.next_cursor`. */
+    cursor?: string;
+}
+export interface RecordListParams extends ListParams {
+    filter?: RecordFilter;
+    sort?: RecordSort;
+    /** Relation or asset fields to embed under `expanded` (at most 5). */
+    expand?: string[];
+}
+export interface RecordGetParams {
+    expand?: string[];
+    include_deleted?: boolean;
+}
+export interface RecordCreateParams<D = G.RecordData> {
+    data: D;
+}
+export interface RecordUpdateParams<D = G.RecordData> {
+    data: RecordDataUpdate<D>;
+}
+export interface RecordCountParams {
+    filter?: RecordFilter;
+}
+export interface RecordScheduleParams {
+    /** A future time, or `null` for none. Omitted keys keep their value. */
+    publish_at?: string | Date | null;
+    unpublish_at?: string | Date | null;
+}
+export type RecordBulkParams = G.BulkRecordsRequest;
+export type RecordDiffParams = NonNullable<G.RecordsDiffData["query"]>;
+export interface RecordSearchParams extends ListParams {
+    /** Needs `filterable` fields (status and timestamps always work). */
+    filter?: RecordFilter;
+    /** Needs a `sortable` field, e.g. `-published_at`; relevance otherwise. */
+    sort?: string;
+    expand?: string[];
+}
+export interface ProjectSearchParams extends ListParams {
+    /** Collection slugs or IDs to search in; every searchable one otherwise. */
+    collections?: string[];
+    filter?: {
+        status?: "draft" | "published";
+    };
+}
+export interface RevisionListParams extends ListParams {
+    filter?: NonNullable<G.RecordRevisionsListData["query"]>["filter"];
+}
+export interface DryRunParams {
+    /** Preview the change without making it. */
+    dry_run?: boolean;
+}
+export interface DeletedListParams extends ListParams {
+    /** List deleted items instead (they can be restored for 30 days). */
+    deleted?: boolean;
+}
+export interface SchemaParams {
+    /** A past schema version; the current one otherwise. */
+    version?: number;
+}
+export type FieldMigrateParams = G.FieldMigrationRequest;
+export type ImageUrlParams = NonNullable<G.AssetsImageUrlData["query"]>;
+export interface DeliveryListParams extends ListParams {
+    status?: "pending" | "succeeded" | "failed";
+}
+export interface AuditEventListParams extends ListParams {
+    filter?: Omit<NonNullable<NonNullable<G.AuditEventsListForProjectData["query"]>["filter"]>, "project_id">;
+    sort?: "id" | "-id";
+}
+/** The metadata of a search page: also an estimate of the total hits. */
+export type SearchMeta = G.SearchResults["meta"];

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/dist/version.d.ts

@@ -0,0 +1 @@
+export declare const VERSION = "0.1.0";

package/dist/version.js

@@ -0,0 +1 @@
+export const VERSION = "0.1.0";

package/dist/webhooks.d.ts

@@ -0,0 +1,47 @@
+import type { Asset, Collection, SchemaChange, Webhook } from "./generated/types.gen.ts";
+import type { NoheadRecord, RecordData } from "./types.ts";
+interface EventBase<Type extends string, Data> {
+    id: string;
+    object: "event";
+    type: Type;
+    created_at: string;
+    project_id: string;
+    data: Data;
+}
+export type RecordEvent<D = RecordData> = EventBase<"record.created" | "record.updated" | "record.deleted" | "record.published" | "record.unpublished", {
+    record: NoheadRecord<D>;
+    revision: number;
+    revision_id: string;
+}>;
+export type AssetEvent = EventBase<"asset.created" | "asset.deleted", {
+    asset: Asset;
+}>;
+export type SchemaChangedEvent = EventBase<"schema.changed", {
+    collection: Collection;
+    schema_change: SchemaChange;
+}>;
+/** Sent by `webhooks.test`. */
+export type WebhookTestEvent = EventBase<"webhook.test", {
+    webhook: Webhook;
+}>;
+/** A webhook request's body, narrowed by `type`. */
+export type WebhookEvent<D = RecordData> = RecordEvent<D> | AssetEvent | SchemaChangedEvent | WebhookTestEvent;
+/** Request headers: a `Headers` object or a plain object (e.g. Node's). */
+export type WebhookHeaders = Headers | Record<string, string | string[] | undefined>;
+export interface UnwrapOptions {
+    /** The webhook's signing secret (`whsec_…`). */
+    secret: string;
+    /** Seconds a timestamp may be off from now. Default 300. */
+    tolerance?: number;
+}
+/**
+ * Checks a webhook request's signature and timestamp and returns its event.
+ * Pass the raw body exactly as received: parsing and re-serializing JSON
+ * changes the bytes, and the signature with them. Throws
+ * `WebhookVerificationError` when anything does not match.
+ *
+ *   const event = await unwrapWebhook(await request.text(), request.headers, { secret })
+ *   if (event.type === "record.published") { … }
+ */
+export declare function unwrapWebhook<D = RecordData>(body: string | ArrayBuffer | Uint8Array, headers: WebhookHeaders, { secret, tolerance }: UnwrapOptions): Promise<WebhookEvent<D>>;
+export {};

package/dist/webhooks.js

@@ -0,0 +1,70 @@
+// Verifying webhook requests (Standard Webhooks), without a client:
+//
+//   import { unwrapWebhook } from "@nohead/sdk/webhooks"
+import { WebhookVerificationError } from "./errors.js";
+/**
+ * Checks a webhook request's signature and timestamp and returns its event.
+ * Pass the raw body exactly as received: parsing and re-serializing JSON
+ * changes the bytes, and the signature with them. Throws
+ * `WebhookVerificationError` when anything does not match.
+ *
+ *   const event = await unwrapWebhook(await request.text(), request.headers, { secret })
+ *   if (event.type === "record.published") { … }
+ */
+export async function unwrapWebhook(body, headers, { secret, tolerance = 300 }) {
+    const id = header(headers, "webhook-id");
+    const timestamp = header(headers, "webhook-timestamp");
+    const signatures = header(headers, "webhook-signature");
+    if (!id || !timestamp || !signatures) {
+        throw new WebhookVerificationError("Missing webhook-id, webhook-timestamp or webhook-signature header");
+    }
+    const sentAt = Number(timestamp);
+    if (!Number.isInteger(sentAt) ||
+        Math.abs(Date.now() / 1000 - sentAt) > tolerance) {
+        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 signed = new TextEncoder().encode(`${id}.${timestamp}.${text}`);
+    for (const entry of signatures.split(" ")) {
+        const [version, signature] = entry.split(",", 2);
+        if (version !== "v1" || !signature)
+            continue;
+        let bytes;
+        try {
+            bytes = decodeBase64(signature, "signature");
+        }
+        catch {
+            continue;
+        }
+        // Constant-time comparison: the platform verifies the HMAC.
+        if (await crypto.subtle.verify("HMAC", key, bytes, signed)) {
+            try {
+                return JSON.parse(text);
+            }
+            catch {
+                throw new WebhookVerificationError("The webhook body is not JSON");
+            }
+        }
+    }
+    throw new WebhookVerificationError("No webhook signature matches");
+}
+function header(headers, name) {
+    if (headers instanceof Headers)
+        return headers.get(name) ?? undefined;
+    const entry = Object.entries(headers).find(([key]) => key.toLowerCase() === name)?.[1];
+    return Array.isArray(entry) ? entry.join(" ") : entry;
+}
+function decodeBase64(value, what) {
+    let binary;
+    try {
+        binary = atob(value);
+    }
+    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;
+}

package/package.json

@@ -1,8 +1,63 @@
 {
   "name": "@nohead/sdk",
-  "version": "0.0.0",
-  "description": "Placeholder for the official TypeScript SDK for the Nohead API. The first real release is 0.1.0.",
+  "version": "0.1.0",
+  "description": "Official TypeScript SDK for the Nohead API",
   "license": "MIT",
   "homepage": "https://nohead.io",
-  "files": ["README.md"]
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nohead-io/nohead-typescript.git"
+  },
+  "bugs": "https://github.com/nohead-io/nohead-typescript/issues",
+  "keywords": [
+    "nohead",
+    "cms",
+    "headless",
+    "api",
+    "sdk"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./webhooks": {
+      "types": "./dist/webhooks.d.ts",
+      "default": "./dist/webhooks.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "CHANGELOG.md"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "generate": "openapi-ts && node scripts/operations.ts",
+    "build": "rm -rf dist && tsc -p tsconfig.build.json",
+    "prepare": "npm run build",
+    "typecheck": "tsc",
+    "lint": "eslint .",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "test": "vitest run",
+    "smoke": "node smoke/smoke.ts",
+    "samples": "node scripts/samples.ts",
+    "typecheck:smoke": "tsc -p smoke"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@hey-api/openapi-ts": "0.99.0",
+    "@types/node": "^26.6.4",
+    "eslint": "^10.12.0",
+    "globals": "^17.13.0",
+    "prettier": "^3.9.9",
+    "typescript": "^6.0.3",
+    "typescript-eslint": "^8.71.0",
+    "vitest": "^5.0.3"
+  }
 }