@nohead/sdk 0.10.0 → 0.12.0

package/CHANGELOG.md

@@ -5,6 +5,22 @@ Changes to `@nohead/sdk` that you can notice. Versions follow
 releases; a change that could break your code is a major one. Each release's
 section is its GitHub release's notes.
 
+## 0.12.0
+
+- `webhooks.create` and `webhooks.update` take `published_only`, and every
+  webhook has it: a published-only webhook sends only the events that change
+  what a published-only API key reads (a record published, unpublished or
+  edited while live, schema changes, changes to assets that published records
+  use), and skips drafts, schedules and edits to unpublished records.
+- Audit events have `note`: the change note (`Nohead-Change-Note`) a record
+  or schema change was made with, or `null`.
+
+## 0.11.0
+
+- `records.diff` takes `richText`, and the client's `richText` now applies to
+  it: a rich text field's `before` and `after` read as HTML or Markdown
+  instead of documents. A revert preview's `changes` follow `richText` too.
+
 ## 0.10.0
 
 - Rich text reads as HTML or Markdown: `richText: "html"` (or `"markdown"`)

package/README.md

@@ -14,6 +14,8 @@ for await (const post of nohead.records.list("posts", {
 }
 ```
 
+The key is a project API key: create one under **API keys** in the [web app](https://app.nohead.io), with the **Read records** scope for this example, and set it as `NOHEAD_API_KEY` in your app's environment (or pass it as `apiKey`, under [Configuration](#configuration)). The SDK doesn't read the key that `nohead login` saves for the CLI: give your app a key of its own.
+
 > **Status:** 0.x until the Nohead API launches.
 
 ## Contents
@@ -159,7 +161,7 @@ await nohead.drafts.get(draftId, {}, { richText: "markdown" })
 ```
 
 - A rich text field's value is then a string: type it as one in the data's type, as above.
-- It applies to the methods that return records or drafts, and to the records they embed with `expand`; a request's `richText` overrides the client's. History (`revisions`) and webhooks keep documents.
+- It applies to the methods that return records or drafts, to the records they embed with `expand`, and to the `before` and `after` of a `diff` or a revert preview's `changes`; a request's `richText` overrides the client's. History (`revisions`) and webhooks keep documents.
 - A string you write is read as Markdown, so write back Markdown or the document, never the HTML: with `richText: "html"` on the client, writes answer with HTML too.
 
 ## Pagination

package/dist/generated/operations.gen.js

@@ -98,6 +98,7 @@ export const RICH_TEXT_OPERATIONS = new Set([
     "records_bulk",
     "records_create",
     "records_delete",
+    "records_diff",
     "records_get",
     "records_list",
     "records_publish",

package/dist/generated/types.gen.d.ts

@@ -1083,8 +1083,14 @@ export type RecordList = {
  *
  */
 export type Change = {
+    /**
+     * The field's key now, after any rename (its last key if it was deleted); null if the field no longer exists.
+     */
     field?: string | null;
     field_id?: string;
+    /**
+     * Whether the field has been deleted since.
+     */
     field_deleted?: boolean;
     attribute?: 'published_at' | 'deleted_at';
     kind: 'added' | 'changed' | 'removed';
@@ -1141,6 +1147,9 @@ export type RevertPreview = {
     record_id: string;
     to_revision: number;
     data: RecordData;
+    /**
+     * What the revert would change. Rich text values read as `rich_text` asks, like `data`; a change that HTML or Markdown can't show (an underline, in Markdown) reads the same on both sides.
+     */
     changes: Array<Change>;
 };
 export type FeatureFlags = {
@@ -1222,6 +1231,10 @@ export type WebhookProperties = {
      * The subscribed event types and wildcards (`record.*`, or `*` for all).
      */
     event_types: Array<WebhookSubscription>;
+    /**
+     * Send only events that change what a published-only API key can read: a record's change while it is published (or that publishes, unpublishes, deletes or restores it), schema changes, and changes to assets that published records use. Drafts, schedules, history redactions, uploads and purges are never sent. `webhook.test` always is.
+     */
+    published_only: boolean;
     enabled: boolean;
     /**
      * When the webhook was deleted; null unless it is.
@@ -1327,10 +1340,19 @@ export type AuditEvent = {
      * The client the change came through, when known.
      */
     via: null | Via;
+    /**
+     * The change note (`Nohead-Change-Note`) the change was made with,
+     * read from the revision or schema change the event references, so
+     * record and schema events have one when their change did; null
+     * otherwise, and once a revision's history is pruned.
+     *
+     */
+    note: string | null;
     /**
      * Small, action-specific references, e.g. `revision_id` and
      * `collection_id` for record events, `schema_change_id` for schema
-     * events, `changed` attribute names for updates. Never content.
+     * events, `changed` attribute names for updates (field keys for a
+     * draft's). Never content.
      *
      */
     metadata: {
@@ -1354,12 +1376,20 @@ export type WebhookCreate = {
     url: string;
     description?: string | null;
     event_types: Array<WebhookSubscription>;
+    /**
+     * Send only events that change what a published-only API key can read (`false` by default). It can't be combined with event types it never sends, such as `draft.*`.
+     */
+    published_only?: boolean;
     enabled?: boolean;
 };
 export type WebhookUpdate = {
     url?: string;
     description?: string | null;
     event_types?: Array<WebhookSubscription>;
+    /**
+     * Send only events that change what a published-only API key can read (`false` by default). It can't be combined with event types it never sends, such as `draft.*`.
+     */
+    published_only?: boolean;
     enabled?: boolean;
 };
 export type WebhookDeliveryProperties = {
@@ -3301,6 +3331,10 @@ export type RecordsDiffData = {
     query: {
         from: number;
         to: number;
+        /**
+         * How rich text values read in `changes`: `document`, the stored ProseMirror JSON document, or written as `html` or `markdown`, as records read with `rich_text`. Record history and webhooks keep documents. A change that HTML or Markdown can't show (an underline, in Markdown) reads the same on both sides. In HTML and Markdown, text from before a field became rich text reads as paragraphs; an older value that is no document of today's vocabulary, or a redacted one, is kept as stored.
+         */
+        rich_text?: 'document' | 'html' | 'markdown';
     };
     url: '/v1/records/{record_id}/diff';
 };

package/dist/resources/records.d.ts

@@ -64,8 +64,11 @@ export declare class Records extends Resource {
      * Each record succeeds or fails on its own; see `results`.
      */
     bulk(collection: string, params: RecordBulkParams, options?: WriteOptions & RichTextOptions): APIPromise<RecordBatch>;
-    /** The changes between two revisions. */
-    diff(record: string, params: RecordDiffParams, options?: RequestOptions): APIPromise<RecordDiff>;
+    /**
+     * The changes between two revisions; with `richText`, rich text fields'
+     * `before` and `after` read as HTML or Markdown.
+     */
+    diff(record: string, params: RecordDiffParams, options?: RichTextOptions): APIPromise<RecordDiff>;
     /**
      * Full-text search in one collection, matching its `searchable` fields.
      * Pages through the first 1,000 hits, most relevant first.

package/dist/resources/records.js

@@ -92,7 +92,10 @@ export class Records extends Resource {
     bulk(collection, params, options) {
         return this.core.request("records_bulk", { path: { collection_id: collection }, body: params }, options);
     }
-    /** The changes between two revisions. */
+    /**
+     * The changes between two revisions; with `richText`, rich text fields'
+     * `before` and `after` read as HTML or Markdown.
+     */
     diff(record, params, options) {
         return this.core.request("records_diff", { path: { record_id: record }, query: params }, options);
     }

package/dist/version.d.ts

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

package/dist/version.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nohead/sdk",
-  "version": "0.10.0",
+  "version": "0.12.0",
   "description": "Official TypeScript SDK for the Nohead API",
   "license": "MIT",
   "homepage": "https://nohead.io",