@nohead/sdk 0.2.0 → 0.3.0

package/dist/resources/schema.js

@@ -1,10 +1,10 @@
-import { Resource } from "./resource.js";
+import { listQuery, Resource } from "./resource.js";
 /** Collections of the key's project. `collection` is an ID or slug. */
 export class Collections extends Resource {
     schemaChanges = new SchemaChanges(this.core);
     searchIndex = new SearchIndexes(this.core);
     list(params = {}, options) {
-        return this.core.paginate("collections_list", { query: params }, options);
+        return this.core.paginate("collections_list", { query: listQuery(params, ["deleted"]) }, options);
     }
     get(collection, options) {
         return this.core.request("collections_get", { path: { collection_id: collection } }, options);
@@ -16,7 +16,10 @@ export class Collections extends Resource {
     update(collection, params, options) {
         return this.core.request("collections_update", { path: { collection_id: collection }, body: params }, options);
     }
-    /** Soft-deletes the collection and its records for 30 days. */
+    /**
+     * Soft-deletes the collection and its records: `restore` brings them back
+     * until its `purge_after`.
+     */
     delete(collection, options) {
         return this.core.request("collections_delete", { path: { collection_id: collection } }, options);
     }
@@ -52,11 +55,17 @@ export class SearchIndexes extends Resource {
 /** Fields of a collection. `field` is a field ID (`fld_…`). */
 export class Fields extends Resource {
     list(collection, params = {}, options) {
-        return this.core.paginate("fields_list", { path: { collection_id: collection }, query: params }, options);
+        return this.core.paginate("fields_list", {
+            path: { collection_id: collection },
+            query: listQuery(params, ["deleted"]),
+        }, options);
     }
     create(collection, params, options) {
         return this.core.request("fields_create", { path: { collection_id: collection }, body: params }, options);
     }
+    get(field, options) {
+        return this.core.request("fields_get", { path: { field_id: field } }, options);
+    }
     /**
      * Renames, describes or loosens a field. Changes that rewrite record
      * values (type, `multiple`, tighter rules) are `migrate`.
@@ -64,14 +73,21 @@ export class Fields extends Resource {
     update(field, params, options) {
         return this.core.request("fields_update", { path: { field_id: field }, body: params }, options);
     }
-    /** Soft-deletes the field: its values return with `restore` for 30 days. */
+    /**
+     * Soft-deletes the field: its values come back with `restore` until its
+     * `purge_after`.
+     */
     delete(field, options) {
         return this.core.request("fields_delete", { path: { field_id: field } }, options);
     }
     restore(field, options) {
         return this.core.request("fields_restore", { path: { field_id: field } }, options);
     }
-    /** Puts the collection's fields in this order. */
+    /** The collection's active fields, in order. */
+    order(collection, options) {
+        return this.core.request("fields_get_order", { path: { collection_id: collection } }, options);
+    }
+    /** Puts the collection's fields in this order; lists every active field once. */
     reorder(collection, params, options) {
         return this.core.request("fields_reorder", { path: { collection_id: collection }, body: params }, options);
     }

package/dist/resources/webhooks.d.ts

@@ -1,20 +1,27 @@
 import type { APIPromise, PagePromise } from "../api-promise.ts";
 import type { RequestOptions } from "../core.ts";
-import type { Webhook, WebhookCreate, WebhookDelivery, WebhookDeliveryDetail, WebhookUpdate, WebhookWithSecret } from "../generated/types.gen.ts";
-import type { DeliveryListParams, ListParams, RecordData } from "../types.ts";
+import type { Webhook, WebhookCreate, WebhookDelivery, WebhookDeliveryDetail, WebhookSecret, WebhookSecretWithValue, WebhookUpdate, WebhookWithSecret } from "../generated/types.gen.ts";
+import type { DeletedListParams, DeliveryListParams, ListParams, RecordData } from "../types.ts";
 import { type UnwrapOptions, type WebhookEvent, type WebhookHeaders } from "../webhooks.ts";
 import { Resource } from "./resource.ts";
 /** Webhooks of the key's project. `webhook` is a webhook ID (`wh_…`). */
 export declare class Webhooks extends Resource {
     readonly deliveries: Deliveries;
-    list(params?: ListParams, options?: RequestOptions): PagePromise<Webhook>;
+    readonly secrets: Secrets;
+    list(params?: DeletedListParams, options?: RequestOptions): PagePromise<Webhook>;
     get(webhook: string, options?: RequestOptions): APIPromise<Webhook>;
     /** Subscribes a URL. The response is the only time `secret` is shown. */
     create(params: WebhookCreate, options?: RequestOptions): APIPromise<WebhookWithSecret>;
     update(webhook: string, params: WebhookUpdate, options?: RequestOptions): APIPromise<Webhook>;
+    /** Soft-deletes the webhook: `restore` brings it back until its `purge_after`. */
     delete(webhook: string, options?: RequestOptions): APIPromise<Webhook>;
-    /** A new signing secret; the old one stops working at once. */
-    rotateSecret(webhook: string, options?: RequestOptions): APIPromise<WebhookWithSecret>;
+    restore(webhook: string, options?: RequestOptions): APIPromise<Webhook>;
+    /**
+     * A new signing secret (`secret`, shown only here). The ones before it
+     * keep signing for 24 hours, so receivers can switch without rejecting
+     * deliveries; `secrets.retire` ends one sooner.
+     */
+    rotateSecret(webhook: string, options?: RequestOptions): APIPromise<WebhookSecretWithValue>;
     /** Sends a `webhook.test` event to the URL. */
     test(webhook: string, options?: RequestOptions): APIPromise<WebhookDelivery>;
     /**
@@ -27,6 +34,13 @@ export declare class Webhooks extends Resource {
 export declare class Deliveries extends Resource {
     list(webhook: string, params?: DeliveryListParams, options?: RequestOptions): PagePromise<WebhookDelivery>;
     get(delivery: string, options?: RequestOptions): APIPromise<WebhookDeliveryDetail>;
-    /** Sends the event again. */
+    /** Sends the event again now, as a new attempt. */
     retry(delivery: string, options?: RequestOptions): APIPromise<WebhookDelivery>;
 }
+/** A webhook's signing secrets. `secret` is a secret ID (`whs_…`). */
+export declare class Secrets extends Resource {
+    /** Those signing deliveries now, oldest first, without their values. */
+    list(webhook: string, params?: ListParams, options?: RequestOptions): PagePromise<WebhookSecret>;
+    /** Stops signing with it now. The newest can't be retired: rotate first. */
+    retire(secret: string, options?: RequestOptions): APIPromise<WebhookSecret>;
+}

package/dist/resources/webhooks.js

@@ -1,10 +1,11 @@
 import { unwrapWebhook, } from "../webhooks.js";
-import { Resource } from "./resource.js";
+import { listQuery, Resource } from "./resource.js";
 /** Webhooks of the key's project. `webhook` is a webhook ID (`wh_…`). */
 export class Webhooks extends Resource {
     deliveries = new Deliveries(this.core);
+    secrets = new Secrets(this.core);
     list(params = {}, options) {
-        return this.core.paginate("webhooks_list", { query: params }, options);
+        return this.core.paginate("webhooks_list", { query: listQuery(params, ["deleted"]) }, options);
     }
     get(webhook, options) {
         return this.core.request("webhooks_get", { path: { webhook_id: webhook } }, options);
@@ -16,10 +17,18 @@ export class Webhooks extends Resource {
     update(webhook, params, options) {
         return this.core.request("webhooks_update", { path: { webhook_id: webhook }, body: params }, options);
     }
+    /** Soft-deletes the webhook: `restore` brings it back until its `purge_after`. */
     delete(webhook, options) {
         return this.core.request("webhooks_delete", { path: { webhook_id: webhook } }, options);
     }
-    /** A new signing secret; the old one stops working at once. */
+    restore(webhook, options) {
+        return this.core.request("webhooks_restore", { path: { webhook_id: webhook } }, options);
+    }
+    /**
+     * A new signing secret (`secret`, shown only here). The ones before it
+     * keep signing for 24 hours, so receivers can switch without rejecting
+     * deliveries; `secrets.retire` ends one sooner.
+     */
     rotateSecret(webhook, options) {
         return this.core.request("webhooks_rotate_secret", { path: { webhook_id: webhook } }, options);
     }
@@ -38,13 +47,24 @@ export class Webhooks extends Resource {
 /** Delivery attempts of a webhook's events. */
 export class Deliveries extends Resource {
     list(webhook, params = {}, options) {
-        return this.core.paginate("webhook_deliveries_list", { path: { webhook_id: webhook }, query: params }, options);
+        return this.core.paginate("webhook_deliveries_list", { path: { webhook_id: webhook }, query: listQuery(params, ["status"]) }, options);
     }
     get(delivery, options) {
         return this.core.request("webhook_deliveries_get", { path: { delivery_id: delivery } }, options);
     }
-    /** Sends the event again. */
+    /** Sends the event again now, as a new attempt. */
     retry(delivery, options) {
         return this.core.request("webhook_deliveries_retry", { path: { delivery_id: delivery } }, options);
     }
 }
+/** A webhook's signing secrets. `secret` is a secret ID (`whs_…`). */
+export class Secrets extends Resource {
+    /** Those signing deliveries now, oldest first, without their values. */
+    list(webhook, params = {}, options) {
+        return this.core.paginate("webhook_secrets_list", { path: { webhook_id: webhook }, query: params }, options);
+    }
+    /** Stops signing with it now. The newest can't be retired: rotate first. */
+    retire(secret, options) {
+        return this.core.request("webhook_secrets_retire", { path: { secret_id: secret } }, options);
+    }
+}

package/dist/types.d.ts

@@ -10,19 +10,47 @@ export type * from "./generated/schemas.gen.ts";
 export type NoheadRecord<D = G.RecordData> = Omit<G.Record, "data"> & {
     data: D;
 };
+/**
+ * A draft whose `data` (the record's values as they read after the merge)
+ * has the shape `D`, as on `NoheadRecord<D>`. Also `Nohead.Draft`.
+ */
+export type NoheadDraft<D = G.RecordData> = Omit<G.Draft, "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".
+ * Operators for one key. `ne` matches records without a value; on fields
+ * with several values `eq`, `ne` and `in` mean contains, does not contain and
+ * contains any of. Ranges take numbers and dates (`"today"`, `"now"`, or a
+ * day, which covers that day in the field's time zone).
+ */
+export interface FilterOperators<V = FilterValue> {
+    eq?: V;
+    ne?: V;
+    gt?: V;
+    gte?: V;
+    lt?: V;
+    lte?: V;
+    /** Any of these (up to 100). */
+    in?: V[];
+    /** Has a value (`true`) or has none (`false`). */
+    exists?: boolean;
+}
+/**
+ * Filters, combined with AND: a value to equal, or operators, e.g.
+ * `{ published_at: { exists: true }, price: { lt: 50 }, category: { in: ["shoes", "bags"] } }`.
+ * `published_at: { exists }` says whether records are published; record
+ * lists and counts also filter `created_at`, `updated_at` and `published_at`
+ * by range. `deleted: true` lists deleted records instead.
  */
 export interface RecordFilter {
-    status?: "draft" | "published";
+    published_at?: FilterOperators<string | Date>;
     deleted?: boolean;
-    [apiKey: string]: FilterValue | undefined;
+    [apiKey: string]: FilterValue | FilterOperators | undefined;
 }
 export type RecordSort = NonNullable<NonNullable<G.RecordsListData["query"]>["sort"]>;
 export interface ListParams {
@@ -37,9 +65,9 @@ export interface RecordListParams extends ListParams {
     /** Relation or asset fields to embed under `expanded` (at most 5). */
     expand?: string[];
 }
+/** A deleted record is returned too, with `deleted_at` and `purge_after`. */
 export interface RecordGetParams {
     expand?: string[];
-    include_deleted?: boolean;
 }
 export interface RecordCreateParams<D = G.RecordData> {
     data: D;
@@ -47,18 +75,44 @@ export interface RecordCreateParams<D = G.RecordData> {
 export interface RecordUpdateParams<D = G.RecordData> {
     data: RecordDataUpdate<D>;
 }
+/** `data` over the record's values, or with `from_revision`, an earlier revision's. */
+export interface DraftCreateParams<D = G.RecordData> {
+    data?: RecordDataUpdate<D>;
+    from_revision?: number;
+}
+export interface DraftUpdateParams<D = G.RecordData> {
+    data: RecordDataUpdate<D>;
+}
+export interface DraftGetParams {
+    /** Relation or asset fields to embed under `expanded` (at most 5). */
+    expand?: string[];
+}
+export interface DraftListParams extends ListParams {
+    /** One record's draft, or several records' (up to 100). */
+    record_id?: string | string[];
+    sort?: "updated_at" | "-updated_at";
+}
+export interface DraftScheduleParams {
+    /** When to merge the draft: a future time. */
+    merge_at: string | Date;
+}
 export interface RecordCountParams {
     filter?: RecordFilter;
 }
+/** The whole schedule: a time left out is cleared, as `null` is. */
 export interface RecordScheduleParams {
-    /** A future time, or `null` for none. Omitted keys keep their value. */
+    /** A future time, or `null` for none. */
     publish_at?: string | Date | null;
     unpublish_at?: string | Date | null;
 }
-export type RecordBulkParams = G.BulkRecordsRequest;
+export interface ScheduledChangeListParams extends ListParams {
+    /** Soonest first by default (`at`). */
+    sort?: "at" | "-at";
+}
+export type RecordBulkParams = G.RecordBatchRequest;
 export type RecordDiffParams = NonNullable<G.RecordsDiffData["query"]>;
 export interface RecordSearchParams extends ListParams {
-    /** Needs `filterable` fields (status and timestamps always work). */
+    /** Needs `filterable` fields (`published_at: { exists }` always works). */
     filter?: RecordFilter;
     /** Needs a `sortable` field, e.g. `-published_at`; relevance otherwise. */
     sort?: string;
@@ -67,19 +121,36 @@ export interface RecordSearchParams extends ListParams {
 export interface ProjectSearchParams extends ListParams {
     /** Collection slugs or IDs to search in; every searchable one otherwise. */
     collections?: string[];
+    /** `{ published_at: { exists: true } }`: published records only (or unpublished, `false`). */
     filter?: {
-        status?: "draft" | "published";
+        published_at?: {
+            exists: boolean;
+        };
     };
 }
+/** A time range, e.g. `{ gte: "2026-10-01T00:00:00Z", lt: new Date() }`. */
+export interface TimeRange {
+    gte?: string | Date;
+    gt?: string | Date;
+    lte?: string | Date;
+    lt?: string | Date;
+}
+/** Filters of a record's revisions, combined with AND. */
+export interface RevisionFilter {
+    operation?: G.RecordRevisionOperation;
+    /** A user (`usr_…`) or API key (`key_…`). */
+    actor_id?: string;
+    created_at?: TimeRange;
+}
 export interface RevisionListParams extends ListParams {
-    filter?: NonNullable<G.RecordRevisionsListData["query"]>["filter"];
+    filter?: RevisionFilter;
 }
 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). */
+    /** List deleted items instead (they can be restored until `purge_after`). */
     deleted?: boolean;
 }
 export interface AssetListParams extends DeletedListParams {
@@ -95,12 +166,28 @@ export interface SchemaParams {
     version?: number;
 }
 export type FieldMigrateParams = G.FieldMigrationRequest;
+export interface FieldReorderParams {
+    /** Every active field of the collection, once each, in the new order. */
+    field_ids: string[];
+}
 export type ImageUrlParams = NonNullable<G.AssetsImageUrlData["query"]>;
 export interface DeliveryListParams extends ListParams {
     status?: "pending" | "succeeded" | "failed";
 }
+/** Filters of the activity log, combined with AND. */
+export interface AuditEventFilter {
+    /** An event type, or a prefix with a trailing `.*` (`record.*`). */
+    type?: string;
+    /** What events are about (`record`, `field`…): one type, or any of several. */
+    resource_type?: string | string[];
+    resource_id?: string;
+    actor_type?: "user" | "api_key" | "system";
+    /** A user (`usr_…`) or API key (`key_…`). */
+    actor_id?: string;
+    created_at?: TimeRange;
+}
 export interface AuditEventListParams extends ListParams {
-    filter?: Omit<NonNullable<NonNullable<G.AuditEventsListForProjectData["query"]>["filter"]>, "project_id">;
+    filter?: AuditEventFilter;
     sort?: "id" | "-id";
 }
 /** The metadata of a search page: also an estimate of the total hits. */

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const VERSION = "0.2.0";
+export declare const VERSION = "0.3.0";

package/dist/version.js

@@ -1 +1 @@
-export const VERSION = "0.2.0";
+export const VERSION = "0.3.0";

package/dist/webhooks.d.ts

@@ -1,35 +1,55 @@
-import type { Asset, Collection, SchemaChange, Webhook } from "./generated/types.gen.ts";
-import type { NoheadRecord, RecordData } from "./types.ts";
+import type * as G from "./generated/types.gen.ts";
+import type { NoheadDraft, NoheadRecord, RecordData } from "./types.ts";
 interface EventBase<Type extends string, Data> {
     id: string;
     object: "event";
     type: Type;
     created_at: string;
     project_id: string;
+    /** Who made the change. An integration that writes back can skip its own. */
+    actor: G.Actor;
+    /** The client the change came through, when known. */
+    via: G.Via | null;
     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;
+/** The event types that start with `prefix`. */
+type TypesOf<Prefix extends string> = Extract<G.WebhookEventType, `${Prefix}.${string}`>;
+/**
+ * A change to a record. `record` is the record as the change's revision left
+ * it, or as it is now for events without a revision (`record.scheduled`,
+ * `record.unscheduled`, `record.schedule_failed`, `record.redacted`); `null`
+ * once the record is purged.
+ */
+export type RecordEvent<D = RecordData> = EventBase<TypesOf<"record">, Omit<G.RecordEventData, "record"> & {
+    record: NoheadRecord<D> | null;
 }>;
-export type SchemaChangedEvent = EventBase<"schema.changed", {
-    collection: Collection;
-    schema_change: SchemaChange;
+/**
+ * A change to a draft. `draft` is the draft as it is now; `null` once merged
+ * or discarded, and while its record is deleted.
+ */
+export type DraftEvent<D = RecordData> = EventBase<TypesOf<"draft">, Omit<G.DraftEventData, "draft"> & {
+    draft: NoheadDraft<D> | null;
 }>;
+/** An asset as it is now; only its `id` and `object` once it is purged. */
+export type AssetEvent = EventBase<TypesOf<"asset">, G.AssetEventData>;
+/**
+ * A schema change: the collection as it left it, and the change; a field's
+ * events also name the field (`field_id`).
+ */
+export type SchemaEvent = EventBase<Exclude<TypesOf<"collection" | "field">, "field.alias_removed">, G.SchemaEventData>;
+/** A renamed field's old API key stopped answering before it expired. */
+export type FieldAliasRemovedEvent = EventBase<"field.alias_removed", G.FieldAliasEventData>;
 /** Sent by `webhooks.test`. */
-export type WebhookTestEvent = EventBase<"webhook.test", {
-    webhook: Webhook;
-}>;
+export type WebhookTestEvent = EventBase<"webhook.test", G.WebhookTestEventData>;
 /** A webhook request's body, narrowed by `type`. */
-export type WebhookEvent<D = RecordData> = RecordEvent<D> | AssetEvent | SchemaChangedEvent | WebhookTestEvent;
+export type WebhookEvent<D = RecordData> = RecordEvent<D> | DraftEvent<D> | AssetEvent | SchemaEvent | FieldAliasRemovedEvent | 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_…`). */
+    /**
+     * The webhook's signing secret (`whsec_…`). While a rotation overlaps,
+     * requests carry a signature for each secret, so either one verifies.
+     */
     secret: string;
     /** Seconds a timestamp may be off from now. Default 300. */
     tolerance?: number;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nohead/sdk",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Official TypeScript SDK for the Nohead API",
   "license": "MIT",
   "homepage": "https://nohead.io",
@@ -53,6 +53,7 @@
     "@eslint/js": "^10.0.1",
     "@hey-api/openapi-ts": "0.99.0",
     "@types/node": "^26.6.4",
+    "ajv": "^8.20.0",
     "eslint": "^10.12.0",
     "globals": "^17.13.0",
     "prettier": "^3.9.9",