@37signals/basecamp 0.12.0 → 0.13.0

package/dist/services/cards-extensions.js

@@ -1,38 +1,42 @@
 import { CardsService as GeneratedCardsService } from "../generated/services/cards.js";
 /**
- * CardsService with a merge-safe `update` on top of the generated surface
+ * CardsService with a presence-aware `update` on top of the generated surface
  * (`get`, `updateVerbatim`, `move`, ...).
  *
- * BC3 builds the card's update params as `{ due_on: nil }.merge(card_params)`
- * (`kanban/cards_controller.rb`), so **any** update whose body omits `due_on`
- * erases the card's due date. A sparse PUT — the natural thing to write — is
- * therefore destructive on the raw endpoint.
+ * BC3's `kanban/cards_controller.rb` builds a JSON card update's params
+ * straight from `card_params` (basecamp/bc3#12521), so on the JSON
+ * representation an omitted key means **leave unchanged** — `due_on` included.
+ * Clearing the due date is asked for explicitly: the server accepts JSON `null`
+ * or `""`, and this SDK sends `""`, because a null would violate body
+ * compaction (SPEC §18). Only the HTML/turbo_stream web forms still default an
+ * omitted `due_on` to nil (`card_params.with_defaults(due_on: nil)`), which is
+ * how the JSON path could be made presence-aware without disturbing the web
+ * contract.
  *
- * `update` composes the public `get` and `updateVerbatim` methods, so hooks
- * observe the two real wire operations rather than a synthetic composite.
+ * `update` therefore sends exactly what the caller addressed, in a single PUT.
+ * It differs from `updateVerbatim` only in accepting `dueOn: null` and encoding
+ * it as the wire spelling of a clear.
  */
 export class CardsService extends GeneratedCardsService {
     /**
      * Updates a card without disturbing fields you did not mention.
      *
-     * Fetches the card first and resends its existing due date when you left
-     * `dueOn` unaddressed — so the extra GET is paid for only in the case where
-     * the API would otherwise destroy something. Naming `dueOn` explicitly (a
-     * date, or `null` to clear) skips the fetch entirely.
+     * One request. A field you omit is omitted from the body and the server
+     * leaves it alone; `dueOn: null` clears the due date.
      *
-     * Not atomic: a concurrent due-date change landing between the GET and the
-     * PUT is overwritten with the value this call read. The window is one
-     * round-trip. Use `updateVerbatim` to send a single request and manage
-     * `due_on` yourself.
+     * Earlier releases read the card back first and resent its due date, because
+     * a JSON update that omitted `due_on` used to erase it. bc3#12521 removed
+     * that behaviour, so the extra round-trip — and the race between the read and
+     * the write — is gone.
      *
      * @param cardId - The card ID
-     * @param req - Fields to set; omitted fields are preserved
+     * @param req - Fields to set; omitted fields are left unchanged
      * @returns The updated Card
      * @throws {BasecampError} If the request fails
      *
      * @example
      * ```ts
-     * // Retitle without losing the due date.
+     * // Retitle without touching the due date.
      * await client.cards.update(123, { title: "New title" });
      *
      * // Clear the due date.
@@ -47,20 +51,13 @@ export class CardsService extends GeneratedCardsService {
             body.content = req.content;
         if (req.assigneeIds !== undefined)
             body.assigneeIds = req.assigneeIds;
-        if (req.dueOn === undefined) {
-            // Unaddressed: preserve whatever is there now.
-            const current = await this.get(cardId);
-            // The Card response carries wire-shaped keys; the request builder takes
-            // camelCase.
-            if (current.due_on)
-                body.dueOn = current.due_on;
-        }
-        else if (req.dueOn !== null) {
-            body.dueOn = req.dueOn;
-        }
-        // req.dueOn === null falls through with dueOn unset: an omitted due_on is
-        // how the API clears the date, so omission IS the clear encoding. Sending
-        // `{"due_on": null}` would violate body compaction (SPEC §18).
+        // `due_on` stays off the wire unless the caller addressed it, which the
+        // server reads as "leave the due date alone". A date sets it; `null` asks
+        // for a clear and is sent as `""` — the server casts the blank to nil (a
+        // BC3 server test pins it), while `{"due_on": null}` would violate body
+        // compaction (SPEC §18) and omission would now be silently ignored.
+        if (req.dueOn !== undefined)
+            body.dueOn = req.dueOn ?? "";
         return this.updateVerbatim(cardId, body);
     }
 }

package/dist/services/cards-extensions.js.map

@@ -1 +1 @@
-{"version":3,"file":"cards-extensions.js","sourceRoot":"","sources":["../../src/services/cards-extensions.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,IAAI,qBAAqB,EAAE,MAAM,gCAAgC,CAAC;AAmCvF;;;;;;;;;;;GAWG;AACH,MAAM,OAAO,YAAa,SAAQ,qBAAqB;IACrD;;;;;;;;;;;;;;;;;;;;;;;;;;OA0BG;IACH,KAAK,CAAC,MAAM,CAAC,MAAc,EAAE,GAAsB;QACjD,MAAM,IAAI,GAKN,EAAE,CAAC;QAEP,IAAI,GAAG,CAAC,KAAK,KAAK,SAAS;YAAE,IAAI,CAAC,KAAK,GAAG,GAAG,CAAC,KAAK,CAAC;QACpD,IAAI,GAAG,CAAC,OAAO,KAAK,SAAS;YAAE,IAAI,CAAC,OAAO,GAAG,GAAG,CAAC,OAAO,CAAC;QAC1D,IAAI,GAAG,CAAC,WAAW,KAAK,SAAS;YAAE,IAAI,CAAC,WAAW,GAAG,GAAG,CAAC,WAAW,CAAC;QAEtE,IAAI,GAAG,CAAC,KAAK,KAAK,SAAS,EAAE,CAAC;YAC5B,+CAA+C;YAC/C,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;YACvC,wEAAwE;YACxE,aAAa;YACb,IAAI,OAAO,CAAC,MAAM;gBAAE,IAAI,CAAC,KAAK,GAAG,OAAO,CAAC,MAAM,CAAC;QAClD,CAAC;aAAM,IAAI,GAAG,CAAC,KAAK,KAAK,IAAI,EAAE,CAAC;YAC9B,IAAI,CAAC,KAAK,GAAG,GAAG,CAAC,KAAK,CAAC;QACzB,CAAC;QACD,0EAA0E;QAC1E,0EAA0E;QAC1E,+DAA+D;QAE/D,OAAO,IAAI,CAAC,cAAc,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;IAC3C,CAAC;CACF"}
+{"version":3,"file":"cards-extensions.js","sourceRoot":"","sources":["../../src/services/cards-extensions.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,IAAI,qBAAqB,EAAE,MAAM,gCAAgC,CAAC;AAoCvF;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,OAAO,YAAa,SAAQ,qBAAqB;IACrD;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,KAAK,CAAC,MAAM,CAAC,MAAc,EAAE,GAAsB;QACjD,MAAM,IAAI,GAKN,EAAE,CAAC;QAEP,IAAI,GAAG,CAAC,KAAK,KAAK,SAAS;YAAE,IAAI,CAAC,KAAK,GAAG,GAAG,CAAC,KAAK,CAAC;QACpD,IAAI,GAAG,CAAC,OAAO,KAAK,SAAS;YAAE,IAAI,CAAC,OAAO,GAAG,GAAG,CAAC,OAAO,CAAC;QAC1D,IAAI,GAAG,CAAC,WAAW,KAAK,SAAS;YAAE,IAAI,CAAC,WAAW,GAAG,GAAG,CAAC,WAAW,CAAC;QAEtE,wEAAwE;QACxE,0EAA0E;QAC1E,yEAAyE;QACzE,wEAAwE;QACxE,oEAAoE;QACpE,IAAI,GAAG,CAAC,KAAK,KAAK,SAAS;YAAE,IAAI,CAAC,KAAK,GAAG,GAAG,CAAC,KAAK,IAAI,EAAE,CAAC;QAE1D,OAAO,IAAI,CAAC,cAAc,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;IAC3C,CAAC;CACF"}

package/dist/services/documents-extensions.d.ts

@@ -0,0 +1,122 @@
+import { DocumentsService as GeneratedDocumentsService } from "../generated/services/documents.js";
+import type { Document } from "../generated/services/documents.js";
+/**
+ * Request parameters for update. Both fields are optional: an omitted field
+ * is left untouched on the document, guaranteed. An explicitly-passed empty
+ * string is a set (clears the field).
+ */
+export interface UpdateDocumentRequest {
+    /** Plain-text title. Omit to leave unchanged; `""` clears it. */
+    title?: string;
+    /** Rich text body (HTML). Omit to leave unchanged; `""` clears it. */
+    content?: string;
+}
+/**
+ * A document's full writable state, handed to the `edit` callback. The whole
+ * object is PUT back to the server, so clearing a field means setting it empty
+ * (`""`) — there is no third state. The writable set is exactly
+ * `{title, content}`.
+ */
+export interface DocumentFields {
+    /** Plain-text title. Set `""` to clear — the document then reads back as "Untitled". */
+    title: string;
+    /** Rich text body (HTML). Set `""` to clear. */
+    content: string;
+}
+/**
+ * DocumentsService with merge-safe `update` and read-modify-write `edit` on
+ * top of the generated surface (`get`, `replace`, ...).
+ *
+ * `PUT /{accountId}/documents/{documentId}` is a full replace: BC3's
+ * `DocumentsController#update` builds a brand-new `Document` from only the
+ * permitted params and swaps the recordable wholesale, so a sparse PUT that
+ * omits `content` erases it. Omitting `title` erases that too — the document
+ * then reads back as `"Untitled"`, because `Document#title` falls back when
+ * blank. Neither field is presence-validated, so **neither omission is a 422**;
+ * both are a `200` that quietly clears. What BC3 does require is the wrapping
+ * `document` object, so a body naming neither field is a `400`.
+ *
+ * Both methods compose the public `get` and `replace` methods, so hooks
+ * observe the two wire operations (`GetDocument` then `ReplaceDocument`), not
+ * a synthetic composite.
+ *
+ * Publishing a draft (`status: "active"`) is not part of this surface: the
+ * spec models only `title` and `content`, and BC3 rejects a status-only update
+ * for the same reason it rejects an empty body.
+ */
+export declare class DocumentsService extends GeneratedDocumentsService {
+    /**
+     * Sets the given fields on a document and preserves everything else: GETs
+     * the current document, overlays the explicitly-set request fields, and PUTs
+     * the full representation back. An omitted (`undefined`) field is untouched,
+     * guaranteed; an explicitly-passed `""` clears.
+     *
+     * Not atomic: there is no conditional-update signal on this endpoint, so a
+     * concurrent write between the GET and PUT is overwritten — last write wins
+     * for the whole representation. The window is one round-trip. Use `replace`
+     * to overwrite deliberately.
+     *
+     * @param documentId - The document ID
+     * @param req - Fields to set; omitted fields are preserved
+     * @returns The updated Document
+     * @throws {BasecampError} If the request fails
+     *
+     * @example
+     * ```ts
+     * // Retitle without erasing the body.
+     * await client.documents.update(123, { title: "Q3 Plan" });
+     * ```
+     */
+    update(documentId: number, req: UpdateDocumentRequest): Promise<Document>;
+    /**
+     * Applies a read-modify-write callback to a document: GETs the current
+     * document, hands the callback its full writable representation, and PUTs
+     * the whole thing back. Clearing a field means setting it empty (`""`) — an
+     * untouched field keeps its current value. If the callback throws (or
+     * rejects), the edit aborts and nothing is written.
+     *
+     * Not atomic: there is no conditional-update signal on this endpoint, so a
+     * concurrent write between the GET and PUT is overwritten — last write wins
+     * for the whole representation. The window is one round-trip. Use `replace`
+     * to overwrite deliberately.
+     *
+     * @param documentId - The document ID
+     * @param fn - Callback that mutates the document's writable fields in place
+     * @returns The updated Document
+     * @throws {BasecampError} If the request fails
+     *
+     * @example
+     * ```ts
+     * await client.documents.edit(123, (d) => {
+     *   d.title = `🚨 ${d.title}`;
+     *   d.content = ""; // clearing = setting empty on a full object
+     * });
+     * ```
+     */
+    edit(documentId: number, fn: (d: DocumentFields) => void | Promise<void>): Promise<Document>;
+    /**
+     * Fetches the document and derives its full writable state.
+     *
+     * Every value here is resent in the full-replace PUT, so every value is
+     * validated before it is read. `?? ""` coalesces only `null` and
+     * `undefined`, leaving corruption wide open: `false`, `0`, `[]`, `{}`, `42`,
+     * `true` and friends would all be forwarded **verbatim** and written to the
+     * document on a call that never mentioned the field. Nothing below this
+     * rejects them — `schema.d.ts` is erased at build time, so `Document` is a
+     * compile-time claim about runtime data. See `merge-safe.ts` and #576.
+     *
+     * The two writable fields read differently because the spec models them
+     * differently: `title` is `@required`, so absent or null is malformed;
+     * `content` is optional, so absent or null is a genuinely empty body.
+     */
+    private currentFields;
+    /**
+     * PUTs the full writable state via `replace`. Both fields are always sent,
+     * empties included: on a full-replace endpoint `""` is how a clear is
+     * expressed — never JSON null (SPEC §18 body compaction), and never by
+     * omission, which would leave the field to the server's own clear-by-default
+     * and read as an accident rather than an intent.
+     */
+    private putFields;
+}
+//# sourceMappingURL=documents-extensions.d.ts.map

package/dist/services/documents-extensions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"documents-extensions.d.ts","sourceRoot":"","sources":["../../src/services/documents-extensions.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,IAAI,yBAAyB,EAAE,MAAM,oCAAoC,CAAC;AACnG,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,oCAAoC,CAAC;AAMnE;;;;GAIG;AACH,MAAM,WAAW,qBAAqB;IACpC,iEAAiE;IACjE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,sEAAsE;IACtE,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;;GAKG;AACH,MAAM,WAAW,cAAc;IAC7B,wFAAwF;IACxF,KAAK,EAAE,MAAM,CAAC;IACd,gDAAgD;IAChD,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,qBAAa,gBAAiB,SAAQ,yBAAyB;IAC7D;;;;;;;;;;;;;;;;;;;;;OAqBG;IACG,MAAM,CAAC,UAAU,EAAE,MAAM,EAAE,GAAG,EAAE,qBAAqB,GAAG,OAAO,CAAC,QAAQ,CAAC;IAO/E;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACG,IAAI,CACR,UAAU,EAAE,MAAM,EAClB,EAAE,EAAE,CAAC,CAAC,EAAE,cAAc,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,GAC9C,OAAO,CAAC,QAAQ,CAAC;IAMpB;;;;;;;;;;;;;;OAcG;YACW,aAAa;IAa3B;;;;;;OAMG;IACH,OAAO,CAAC,SAAS;CAGlB"}

package/dist/services/documents-extensions.js

@@ -0,0 +1,125 @@
+import { DocumentsService as GeneratedDocumentsService } from "../generated/services/documents.js";
+import { requireRecord, requiredWritableString, writableString } from "./merge-safe.js";
+/** The deliberate-overwrite escape hatch named in this composite's error hints. */
+const ESCAPE = "replace()";
+/**
+ * DocumentsService with merge-safe `update` and read-modify-write `edit` on
+ * top of the generated surface (`get`, `replace`, ...).
+ *
+ * `PUT /{accountId}/documents/{documentId}` is a full replace: BC3's
+ * `DocumentsController#update` builds a brand-new `Document` from only the
+ * permitted params and swaps the recordable wholesale, so a sparse PUT that
+ * omits `content` erases it. Omitting `title` erases that too — the document
+ * then reads back as `"Untitled"`, because `Document#title` falls back when
+ * blank. Neither field is presence-validated, so **neither omission is a 422**;
+ * both are a `200` that quietly clears. What BC3 does require is the wrapping
+ * `document` object, so a body naming neither field is a `400`.
+ *
+ * Both methods compose the public `get` and `replace` methods, so hooks
+ * observe the two wire operations (`GetDocument` then `ReplaceDocument`), not
+ * a synthetic composite.
+ *
+ * Publishing a draft (`status: "active"`) is not part of this surface: the
+ * spec models only `title` and `content`, and BC3 rejects a status-only update
+ * for the same reason it rejects an empty body.
+ */
+export class DocumentsService extends GeneratedDocumentsService {
+    /**
+     * Sets the given fields on a document and preserves everything else: GETs
+     * the current document, overlays the explicitly-set request fields, and PUTs
+     * the full representation back. An omitted (`undefined`) field is untouched,
+     * guaranteed; an explicitly-passed `""` clears.
+     *
+     * Not atomic: there is no conditional-update signal on this endpoint, so a
+     * concurrent write between the GET and PUT is overwritten — last write wins
+     * for the whole representation. The window is one round-trip. Use `replace`
+     * to overwrite deliberately.
+     *
+     * @param documentId - The document ID
+     * @param req - Fields to set; omitted fields are preserved
+     * @returns The updated Document
+     * @throws {BasecampError} If the request fails
+     *
+     * @example
+     * ```ts
+     * // Retitle without erasing the body.
+     * await client.documents.update(123, { title: "Q3 Plan" });
+     * ```
+     */
+    async update(documentId, req) {
+        const fields = await this.currentFields(documentId);
+        if (req.title !== undefined)
+            fields.title = req.title;
+        if (req.content !== undefined)
+            fields.content = req.content;
+        return this.putFields(documentId, fields);
+    }
+    /**
+     * Applies a read-modify-write callback to a document: GETs the current
+     * document, hands the callback its full writable representation, and PUTs
+     * the whole thing back. Clearing a field means setting it empty (`""`) — an
+     * untouched field keeps its current value. If the callback throws (or
+     * rejects), the edit aborts and nothing is written.
+     *
+     * Not atomic: there is no conditional-update signal on this endpoint, so a
+     * concurrent write between the GET and PUT is overwritten — last write wins
+     * for the whole representation. The window is one round-trip. Use `replace`
+     * to overwrite deliberately.
+     *
+     * @param documentId - The document ID
+     * @param fn - Callback that mutates the document's writable fields in place
+     * @returns The updated Document
+     * @throws {BasecampError} If the request fails
+     *
+     * @example
+     * ```ts
+     * await client.documents.edit(123, (d) => {
+     *   d.title = `🚨 ${d.title}`;
+     *   d.content = ""; // clearing = setting empty on a full object
+     * });
+     * ```
+     */
+    async edit(documentId, fn) {
+        const fields = await this.currentFields(documentId);
+        await fn(fields);
+        return this.putFields(documentId, fields);
+    }
+    /**
+     * Fetches the document and derives its full writable state.
+     *
+     * Every value here is resent in the full-replace PUT, so every value is
+     * validated before it is read. `?? ""` coalesces only `null` and
+     * `undefined`, leaving corruption wide open: `false`, `0`, `[]`, `{}`, `42`,
+     * `true` and friends would all be forwarded **verbatim** and written to the
+     * document on a call that never mentioned the field. Nothing below this
+     * rejects them — `schema.d.ts` is erased at build time, so `Document` is a
+     * compile-time claim about runtime data. See `merge-safe.ts` and #576.
+     *
+     * The two writable fields read differently because the spec models them
+     * differently: `title` is `@required`, so absent or null is malformed;
+     * `content` is optional, so absent or null is a genuinely empty body.
+     */
+    async currentFields(documentId) {
+        const current = requireRecord(await this.get(documentId), {
+            record: "Document",
+            operation: "GetDocument",
+            escape: ESCAPE,
+        });
+        const opts = { record: "Document", escape: ESCAPE };
+        return {
+            title: requiredWritableString(current, "title", opts),
+            content: writableString(current, "content", opts),
+        };
+    }
+    /**
+     * PUTs the full writable state via `replace`. Both fields are always sent,
+     * empties included: on a full-replace endpoint `""` is how a clear is
+     * expressed — never JSON null (SPEC §18 body compaction), and never by
+     * omission, which would leave the field to the server's own clear-by-default
+     * and read as an accident rather than an intent.
+     */
+    putFields(documentId, f) {
+        return this.replace(documentId, { title: f.title, content: f.content });
+    }
+}
+//# sourceMappingURL=documents-extensions.js.map

package/dist/services/documents-extensions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"documents-extensions.js","sourceRoot":"","sources":["../../src/services/documents-extensions.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,IAAI,yBAAyB,EAAE,MAAM,oCAAoC,CAAC;AAEnG,OAAO,EAAE,aAAa,EAAE,sBAAsB,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAExF,mFAAmF;AACnF,MAAM,MAAM,GAAG,WAAW,CAAC;AA2B3B;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,OAAO,gBAAiB,SAAQ,yBAAyB;IAC7D;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,KAAK,CAAC,MAAM,CAAC,UAAkB,EAAE,GAA0B;QACzD,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,aAAa,CAAC,UAAU,CAAC,CAAC;QACpD,IAAI,GAAG,CAAC,KAAK,KAAK,SAAS;YAAE,MAAM,CAAC,KAAK,GAAG,GAAG,CAAC,KAAK,CAAC;QACtD,IAAI,GAAG,CAAC,OAAO,KAAK,SAAS;YAAE,MAAM,CAAC,OAAO,GAAG,GAAG,CAAC,OAAO,CAAC;QAC5D,OAAO,IAAI,CAAC,SAAS,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC;IAC5C,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,KAAK,CAAC,IAAI,CACR,UAAkB,EAClB,EAA+C;QAE/C,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,aAAa,CAAC,UAAU,CAAC,CAAC;QACpD,MAAM,EAAE,CAAC,MAAM,CAAC,CAAC;QACjB,OAAO,IAAI,CAAC,SAAS,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC;IAC5C,CAAC;IAED;;;;;;;;;;;;;;OAcG;IACK,KAAK,CAAC,aAAa,CAAC,UAAkB;QAC5C,MAAM,OAAO,GAAG,aAAa,CAAC,MAAM,IAAI,CAAC,GAAG,CAAC,UAAU,CAAC,EAAE;YACxD,MAAM,EAAE,UAAU;YAClB,SAAS,EAAE,aAAa;YACxB,MAAM,EAAE,MAAM;SACf,CAAC,CAAC;QACH,MAAM,IAAI,GAAG,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC;QACpD,OAAO;YACL,KAAK,EAAE,sBAAsB,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,CAAC;YACrD,OAAO,EAAE,cAAc,CAAC,OAAO,EAAE,SAAS,EAAE,IAAI,CAAC;SAClD,CAAC;IACJ,CAAC;IAED;;;;;;OAMG;IACK,SAAS,CAAC,UAAkB,EAAE,CAAiB;QACrD,OAAO,IAAI,CAAC,OAAO,CAAC,UAAU,EAAE,EAAE,KAAK,EAAE,CAAC,CAAC,KAAK,EAAE,OAAO,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC;IAC1E,CAAC;CACF"}

package/dist/services/merge-safe.d.ts

@@ -0,0 +1,167 @@
+/**
+ * Response guards shared by the merge-safe composites.
+ *
+ * A merge-safe `update`/`edit` GETs a record, reads each writable field, and
+ * PUTs the **full** representation back. The endpoint is full-replace, so every
+ * value read here is written — including one the caller never mentioned. If the
+ * read step coerces or forwards a malformed value instead of refusing it, that
+ * value lands on the record.
+ *
+ * Two failure modes, the same defect wearing different clothes:
+ *
+ * - **erasure** — a falsey value dropped or coalesced away, wiping the field;
+ * - **corruption** — a non-string forwarded verbatim, writing a number,
+ *   boolean, array or object where a string belongs.
+ *
+ * `?? ""` catches only `null` and `undefined`, so it rules out erasure while
+ * leaving corruption wide open — every one of `false`, `0`, `[]`, `{}`, `42`,
+ * `true`, `["x"]` and `{a:1}` rides through unchanged. Testing only for erasure
+ * is what let this class survive five review passes, so both are refused here.
+ *
+ * **The rule: a composite is safe exactly when a decoder *rejects* a
+ * wrong-typed field at runtime — not when a type merely claims one.** Go
+ * (`json.Unmarshal`), Swift (`Codable`) and Kotlin (kotlinx.serialization)
+ * genuinely refuse. TypeScript's `schema.d.ts` is erased at build time, so the
+ * type on a GET result is a compile-time claim nothing validates; structurally
+ * this sits with Python and Ruby, not with Go and Swift (#576).
+ *
+ * Todolists carries its own copy of these guards (#574). #544 flattened the
+ * shape those guards read — dropping the envelope-arm rung, not the guards —
+ * but did not unify them here. A generated validating layer (#578) is the
+ * intended end state for all of them.
+ */
+import { type BasecampError } from "../errors.js";
+/**
+ * Renders a value for an error message without ever throwing.
+ *
+ * The guard's own error path must not fail while explaining a failure.
+ * `JSON.stringify` raises `TypeError` on a circular structure, and a value can
+ * carry a `toJSON` that throws — either would replace a clean `api_error` with
+ * an incidental `TypeError` and lose the diagnosis. The type name is always
+ * available; the rendering is a bonus, capped per SPEC §9 and dropped if it
+ * fails.
+ */
+export declare function describeValue(value: unknown): string;
+/**
+ * Builds the malformed-response error, with the message capped per SPEC §9.
+ *
+ * `api_error`, not `usage`: the value arrived in a successful API response, so
+ * nothing the caller passed is at fault. Statusless — the transport succeeded,
+ * there is no HTTP status to attribute — and non-retryable, because
+ * re-requesting cannot repair a malformed body.
+ */
+export declare function malformedResponse(message: string, hint: string): BasecampError;
+/**
+ * The response must be a JSON object before any field is read.
+ *
+ * One level up from the malformed-*field* guards: a successful GET can return a
+ * scalar, an array, or null. Reading a property off `null` throws a raw
+ * `TypeError`, and off an array or a string it silently yields `undefined`,
+ * which the field guards would then read as "genuinely empty" and write back —
+ * so the envelope needs checking before the fields.
+ */
+export declare function requireRecord(body: unknown, opts: {
+    record: string;
+    operation: string;
+    escape: string;
+}): Record<string, unknown>;
+/**
+ * Reads a writable string field, refusing to pass a malformed one through.
+ *
+ * An absent key or an explicit `null` is genuinely empty — there is nothing to
+ * preserve and `""` is what the server already holds. An actual string passes
+ * verbatim. Anything else is a malformed response and is refused **before** the
+ * PUT, naming the offending field.
+ */
+export declare function writableString(body: Record<string, unknown>, key: string, opts: {
+    record: string;
+    escape: string;
+}): string;
+/**
+ * Reads a writable string the record is *required* to carry.
+ *
+ * {@link writableString} treats an absent key or an explicit `null` as
+ * genuinely empty, which is right for an optional field — `""` is what the
+ * server already holds. It is wrong for a required one. Where the spec marks a
+ * response member `@required` and BC3 can never render it blank, an absent,
+ * null or blank value in a 2xx body is a **malformed response**, not an empty
+ * field. Coalescing it to `""` and sending that in the full-replace PUT would
+ * blank the real value on a call that never mentioned it — #576's defect
+ * exactly.
+ *
+ * Two records rely on this today and for the same reason: `Document#title` is
+ * `super.presence || "Untitled"` and `Schedule::Entry#summary` is
+ * `super.presence || "Untitled"`, so neither can come back blank from a healthy
+ * server.
+ *
+ * The wrong-type branch is delegated to {@link writableString}, so a required
+ * field and an optional one report a non-string identically.
+ */
+export declare function requiredWritableString(body: Record<string, unknown>, key: string, opts: {
+    record: string;
+    escape: string;
+}): string;
+/**
+ * Reads a writable boolean the record is *required* to carry.
+ *
+ * The boolean analogue of {@link requiredWritableString}, and it cannot be
+ * expressed with a truthiness test: the value this guard most needs to admit is
+ * `false`, which every `||`/`if (!x)` idiom would treat as missing and replace
+ * with a default. `ScheduleEntry.all_day` is `NOT NULL` with a `false` default
+ * in BC3 and every partial emits it, so absent or null is a malformed
+ * response — and defaulting it to `false` would silently convert an all-day
+ * event into a midnight-to-midnight timed one on a call that only changed the
+ * summary.
+ *
+ * `0`/`1` are refused rather than coerced, for the same reason
+ * {@link writableString} refuses `42`: JSON has a boolean type and the server
+ * uses it.
+ */
+export declare function requiredWritableBoolean(body: Record<string, unknown>, key: string, opts: {
+    record: string;
+    escape: string;
+}): boolean;
+/**
+ * Reads an *optional* writable boolean, refusing to coerce a malformed one.
+ *
+ * {@link writableString}'s boolean sibling, standing in the same relation to
+ * {@link requiredWritableBoolean} that `writableString` does to
+ * {@link requiredWritableString}: an absent key or an explicit `null` is
+ * genuinely "not set" and returns `false`, because that is what the server
+ * already holds.
+ *
+ * `ScheduleEntry.highlighted` is the case it exists for. The entry partial
+ * emits it unconditionally, but the reduced calendar partial behind
+ * `GetUpcomingSchedule` does not, and both render through the same schema — so
+ * the member is optional and absence is legitimate rather than malformed.
+ *
+ * What still cannot be tolerated is the *wrong type*: a `"yes"` or a `1` must be
+ * refused, not coerced, because a caller who assigns the seeded value straight
+ * back sends whatever it was seeded with. That branch is delegated to
+ * {@link requiredWritableBoolean}, so an optional boolean and a required one
+ * report a non-boolean identically.
+ */
+export declare function writableBoolean(body: Record<string, unknown>, key: string, opts: {
+    record: string;
+    escape: string;
+}): boolean;
+/**
+ * Reads a list of person records and projects it to their integer IDs.
+ *
+ * The analogue of {@link writableString} for the ID-list fields. The `.map()`
+ * it replaces (`(body[key] ?? []).map((p) => p.id)`) has three ways to go wrong
+ * on malformed data: a non-array has no `.map` (a raw `TypeError`), a
+ * non-object element yields `undefined`, and a non-integer `id` rides through
+ * verbatim into the full-replace PUT — the same corruption as a wrong-typed
+ * string, one level down.
+ *
+ * `Number.isInteger` is the test rather than `typeof === "number"`: `1.5` and
+ * `NaN` are numbers and neither is a person ID. Booleans fail it outright,
+ * which is what we want — JavaScript would happily coerce `true` to `1`
+ * downstream.
+ */
+export declare function writableIdList(body: Record<string, unknown>, key: string, opts: {
+    record: string;
+    escape: string;
+}): number[];
+//# sourceMappingURL=merge-safe.d.ts.map

package/dist/services/merge-safe.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"merge-safe.d.ts","sourceRoot":"","sources":["../../src/services/merge-safe.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,OAAO,EAAgC,KAAK,aAAa,EAAE,MAAM,cAAc,CAAC;AAMhF;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAQpD;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,aAAa,CAE9E;AAED;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAC3B,IAAI,EAAE,OAAO,EACb,IAAI,EAAE;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAC1D,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CASzB;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAC5B,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,GAAG,EAAE,MAAM,EACX,IAAI,EAAE;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACvC,MAAM,CAUR;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,sBAAsB,CACpC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,GAAG,EAAE,MAAM,EACX,IAAI,EAAE;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACvC,MAAM,CAUR;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,uBAAuB,CACrC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,GAAG,EAAE,MAAM,EACX,IAAI,EAAE;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACvC,OAAO,CAgBT;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,eAAe,CAC7B,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,GAAG,EAAE,MAAM,EACX,IAAI,EAAE;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACvC,OAAO,CAIT;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,cAAc,CAC5B,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,GAAG,EAAE,MAAM,EACX,IAAI,EAAE;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACvC,MAAM,EAAE,CA+BV"}