@37signals/basecamp 0.12.0 → 0.14.0

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"}

package/dist/services/merge-safe.js

@@ -0,0 +1,217 @@
+/**
+ * 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 { Errors, truncateErrorMessage } from "../errors.js";
+const resendHint = (escape) => "The merge-safe update/edit resend this field verbatim, so a coerced or empty value " +
+    `would overwrite the current one. Use ${escape} to write the record deliberately.`;
+/**
+ * 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 function describeValue(value) {
+    const kind = value === null ? "null" : Array.isArray(value) ? "array" : typeof value;
+    try {
+        const rendered = JSON.stringify(value);
+        return rendered === undefined ? kind : `${kind} ${truncateErrorMessage(rendered)}`;
+    }
+    catch {
+        return kind;
+    }
+}
+/**
+ * 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 function malformedResponse(message, hint) {
+    return Errors.apiError(truncateErrorMessage(message), undefined, { hint, retryable: false });
+}
+/**
+ * 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 function requireRecord(body, opts) {
+    if (typeof body !== "object" || body === null || Array.isArray(body)) {
+        throw malformedResponse(`${opts.operation} returned ${describeValue(body)} where a ${opts.record.toLowerCase()} object was expected`, "The merge-safe update/edit read this record's fields before rewriting them, so a " +
+            `non-object body cannot be used. Use ${opts.escape} to write the record deliberately.`);
+    }
+    return body;
+}
+/**
+ * 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 function writableString(body, key, opts) {
+    const value = body[key];
+    if (value === undefined || value === null)
+        return "";
+    if (typeof value !== "string") {
+        throw malformedResponse(`${opts.record} field "${key}" is not a string: ${describeValue(value)}`, resendHint(opts.escape));
+    }
+    return value;
+}
+/**
+ * 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 function requiredWritableString(body, key, opts) {
+    const value = body[key];
+    if (value === undefined || value === null || (typeof value === "string" && value.trim() === "")) {
+        throw malformedResponse(`${opts.record} field "${key}" is required but the response carried ${describeValue(value)}`, `The merge-safe update/edit resend this field verbatim, so a missing or blank value would ` +
+            `blank the current one. Use ${opts.escape} to write the record deliberately.`);
+    }
+    return writableString(body, key, opts);
+}
+/**
+ * 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 function requiredWritableBoolean(body, key, opts) {
+    const value = body[key];
+    if (value === undefined || value === null) {
+        throw malformedResponse(`${opts.record} field "${key}" is required but the response carried ${describeValue(value)}`, `The merge-safe update/edit resend this field verbatim, so a missing value would replace ` +
+            `the current one with a default. Use ${opts.escape} to write the record deliberately.`);
+    }
+    if (typeof value !== "boolean") {
+        throw malformedResponse(`${opts.record} field "${key}" is not a boolean: ${describeValue(value)}`, resendHint(opts.escape));
+    }
+    return value;
+}
+/**
+ * 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 function writableBoolean(body, key, opts) {
+    const value = body[key];
+    if (value === undefined || value === null)
+        return false;
+    return requiredWritableBoolean(body, key, opts);
+}
+/**
+ * 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 function writableIdList(body, key, opts) {
+    const value = body[key];
+    if (value === undefined || value === null)
+        return [];
+    if (!Array.isArray(value)) {
+        throw malformedResponse(`${opts.record} field "${key}" is not an array: ${describeValue(value)}`, resendHint(opts.escape));
+    }
+    return value.map((element, index) => {
+        if (typeof element !== "object" || element === null || Array.isArray(element)) {
+            throw malformedResponse(`${opts.record} field "${key}"[${index}] is not an object: ${describeValue(element)}`, resendHint(opts.escape));
+        }
+        const id = element["id"];
+        if (id === undefined || id === null) {
+            throw malformedResponse(`${opts.record} field "${key}"[${index}] has no "id"`, resendHint(opts.escape));
+        }
+        if (typeof id !== "number" || !Number.isInteger(id)) {
+            throw malformedResponse(`${opts.record} field "${key}"[${index}].id is not an integer: ${describeValue(id)}`, resendHint(opts.escape));
+        }
+        return id;
+    });
+}
+//# sourceMappingURL=merge-safe.js.map

package/dist/services/merge-safe.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"merge-safe.js","sourceRoot":"","sources":["../../src/services/merge-safe.ts"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,266 @@
+import { SchedulesService as GeneratedSchedulesService } from "../generated/services/schedules.js";
+import type { ScheduleEntry } from "../generated/services/schedules.js";
+/**
+ * Request parameters for `updateEntry`.
+ *
+ * **Addressedness is property presence, not value.** Every field is optional;
+ * a key you leave off the object is not addressed, and a key you set is —
+ * including `{ highlighted: false }`, `{ url: "" }` and
+ * `{ participantIds: [] }`, each of which is a deliberate clear and reaches the
+ * wire. That distinction is the whole point of the carve-out contract below,
+ * so it is tested with `Object.prototype.hasOwnProperty.call`, never with a
+ * truthiness test.
+ *
+ * The fields split in two, and the split is not cosmetic:
+ *
+ * - **full state** — `summary`, `startsAt`, `endsAt`, `description`, `allDay`.
+ *   Always sent, seeded from the read-back when you do not address them,
+ *   because BC3 rebuilds the entry from the submitted params and clears every
+ *   writable field the body omits.
+ * - **addressed-only** — `participantIds`, `url`, `highlighted`, `notify`.
+ *   Sent only when you address them, and never seeded from the read-back. BC3
+ *   preserves the first three on omission (`PRESERVED_ON_OMISSION`), so
+ *   resending them is redundant at best and wrong if the read raced a
+ *   concurrent change. `notify` is a directive rather than state: sending it
+ *   makes BC3 recompute a drafted entry's subscriber list.
+ */
+export interface UpdateScheduleEntryRequest {
+    /** Summary text. Omit to leave unchanged; `""` clears it. */
+    summary?: string;
+    /**
+     * When the entry starts — a bare date (`"2026-06-05"`) for an all-day entry,
+     * a timestamp otherwise. Omit to leave unchanged.
+     */
+    startsAt?: string;
+    /** When the entry ends, in the same spelling as `startsAt`. Omit to leave unchanged. */
+    endsAt?: string;
+    /** Rich text description (HTML). Omit to leave unchanged; `""` clears it. */
+    description?: string;
+    /** Whether the entry occupies whole days. Omit to leave unchanged. */
+    allDay?: boolean;
+    /**
+     * Replaces the entry's participants. Omit to leave them alone — BC3 preserves
+     * them when the request does not address them — or pass `[]` to remove
+     * everyone.
+     *
+     * Never resent on your behalf: the read-back's `participants` are people the
+     * *reader* can see, and echoing them would rewrite the list from a stale view.
+     */
+    participantIds?: number[];
+    /**
+     * The entry's join link — a video-call URL or similar. Omit to leave it
+     * alone; `""` clears it.
+     *
+     * Read back as `join_url`, never as `url`: an entry's `url` is its own
+     * Basecamp API URL. The composite therefore never seeds this from the
+     * response, which would write the API URL into the join link.
+     */
+    url?: string;
+    /** Whether the entry is highlighted on the schedule. Omit to leave it alone; `false` removes it. */
+    highlighted?: boolean;
+    /**
+     * Whether to notify the relevant people. A directive, not state: it is sent
+     * only when you address it, and it is never read back.
+     */
+    notify?: boolean;
+}
+/**
+ * A schedule entry's full writable state, handed to the `editEntry` callback.
+ *
+ * The five full-state members are seeded from the read-back and **always** PUT
+ * back, so clearing one means setting it empty (`""`) — there is no third
+ * state.
+ *
+ * The four carve-outs behave differently and deliberately: they are seeded for
+ * *reading* (so you can inspect the current join link, highlight and
+ * participants before deciding), but they reach the wire **only if you assign
+ * to them**. Assignment is what marks them, not the value you assign — setting
+ * `e.url = e.url` sends the join link, because intent is not recoverable from a
+ * value comparison.
+ */
+export interface ScheduleEntryFields {
+    /** Summary text. Set `""` to clear — the entry then reads back as "Untitled". */
+    summary: string;
+    /** Start date or timestamp, exactly as the server spelled it. */
+    startsAt: string;
+    /** End date or timestamp, exactly as the server spelled it. */
+    endsAt: string;
+    /** Rich text description (HTML). Set `""` to clear. */
+    description: string;
+    /** Whether the entry occupies whole days. */
+    allDay: boolean;
+    /** Current participants, by person ID. Assign to replace them; `[]` removes everyone. */
+    participantIds: number[];
+    /** The current join link (the response's `join_url`), or `""`. Assign to change it. */
+    url: string;
+    /** Whether the entry is currently highlighted. Assign to change it. */
+    highlighted: boolean;
+    /**
+     * Whether to notify the relevant people. Write-only — the API reports no such
+     * field, so this reads back `undefined` until you assign to it.
+     */
+    notify?: boolean;
+}
+/**
+ * SchedulesService with merge-safe `updateEntry` and read-modify-write
+ * `editEntry` on top of the generated surface (`getEntry`, `replaceEntry`,
+ * `createEntry`, `listEntries`, ...).
+ *
+ * `PUT /{accountId}/schedule_entries/{entryId}` is a full replace:
+ * `Schedules::EntriesController#update` rebuilds the recordable from the
+ * submitted params, so a sparse PUT that omits `description` erases it and one
+ * that omits `all_day` turns an all-day event into a midnight-to-midnight timed
+ * one. Neither is a 422 — both are a `200` that quietly clears, which is what
+ * these composites exist to prevent.
+ *
+ * Three writable fields are exempt. BC3 seeds `participant_ids`, `url` and
+ * `highlighted` from the existing recordable when the request does not address
+ * them, so the SDK's job for those is the opposite one: keep them **off** the
+ * wire unless the caller asked for them.
+ *
+ * Both composites compose the public `getEntry` and `replaceEntry`, so hooks
+ * observe the two wire operations under their native identities
+ * (`GetScheduleEntry` then `ReplaceScheduleEntry`) rather than a synthetic
+ * composite.
+ *
+ * **Non-recurring entries only.** `ensure_non_recurring_event` 302-redirects
+ * both `show` and `update` for a recurring entry, and the SDK follows neither:
+ * the GET surfaces as an unexpected body and the PUT as a redirect. Recurrence
+ * itself (`recurrence_schedule`, `recurs_until`, `time_zone_name`) is unmodeled
+ * — BC3 forces all three to nil for a non-recurring entry.
+ */
+export declare class SchedulesService extends GeneratedSchedulesService {
+    /**
+     * Sets the given fields on a schedule entry and preserves everything else:
+     * GETs the current entry, overlays the fields you addressed, and PUTs the
+     * full representation back.
+     *
+     * A key you leave off the request is not addressed. For the five full-state
+     * fields that means "keep what the server has"; for the four carve-outs it
+     * means the key never appears in the body, so BC3's own preservation applies.
+     * An explicitly-passed `""`, `false` or `[]` is an address and 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 full-state fields. The window is one round-trip. Use `replaceEntry`
+     * to overwrite deliberately.
+     *
+     * @param entryId - The entry ID
+     * @param req - Fields to set; unaddressed fields are preserved
+     * @returns The updated ScheduleEntry
+     * @throws {BasecampError} If the request fails, or if the read-back is malformed
+     *
+     * @example
+     * ```ts
+     * // Rename without erasing the description, times or all-day flag.
+     * await client.schedules.updateEntry(123, { summary: "Team Meeting & Kickoff" });
+     *
+     * // Drop the join link and the highlight; participants are left alone.
+     * await client.schedules.updateEntry(123, { url: "", highlighted: false });
+     * ```
+     */
+    updateEntry(entryId: number, req: UpdateScheduleEntryRequest): Promise<ScheduleEntry>;
+    /**
+     * Applies a read-modify-write callback to a schedule entry: GETs the current
+     * entry, hands the callback its writable state, and PUTs the whole thing
+     * back. If the callback throws (or rejects), the edit aborts and nothing is
+     * written.
+     *
+     * The five full-state fields always ride back, so clearing one means setting
+     * it empty and an untouched one keeps its current value. The four carve-outs
+     * (`participantIds`, `url`, `highlighted`, `notify`) are seeded so you can
+     * read them, but they reach the wire only if the callback **assigns** to
+     * them. Assignment is tracked by invocation, not by comparing values:
+     * `e.url = e.url` is a write, because a caller who reassigns the value the
+     * read returned still means "write this", and no diff can recover that
+     * intent.
+     *
+     * 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 full-state fields. The window is one round-trip. Use `replaceEntry`
+     * to overwrite deliberately.
+     *
+     * @param entryId - The entry ID
+     * @param fn - Callback that mutates the entry's writable fields in place
+     * @returns The updated ScheduleEntry
+     * @throws {BasecampError} If the request fails, or if the read-back is malformed
+     *
+     * @example
+     * ```ts
+     * await client.schedules.editEntry(123, (e) => {
+     *   e.summary = `🚨 ${e.summary}`;
+     *   e.description = ""; // clearing = setting empty on a full object
+     *   // participants, join link and highlight are untouched, so they stay off
+     *   // the wire and BC3 keeps them.
+     * });
+     * ```
+     */
+    editEntry(entryId: number, fn: (e: ScheduleEntryFields) => void | Promise<void>): Promise<ScheduleEntry>;
+    /**
+     * Fetches the entry and derives the full-state half of its 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 entry on a
+     * call that never mentioned the field. Nothing below this rejects them —
+     * `schema.d.ts` is erased at build time, so `ScheduleEntry` is a compile-time
+     * claim about runtime data, which puts this composite with Python and Ruby
+     * rather than with Go and Swift. See `merge-safe.ts` and #576.
+     *
+     * The guards differ per field because the spec models the fields
+     * differently:
+     *
+     * - `summary` is `@required` and `Schedule::Entry#summary` is
+     *   `super.presence || "Untitled"`, so blank is impossible from a healthy
+     *   server and absent/null/blank is malformed.
+     * - `starts_at`/`ends_at` are `@required` and `NOT NULL`. The value is a bare
+     *   date for an all-day entry and a timestamp otherwise; it round-trips
+     *   verbatim rather than through a `Date`, which would normalise the two
+     *   spellings into one and rewrite the entry's shape.
+     * - `all_day` is `@required`, `NOT NULL DEFAULT false`. It needs the boolean
+     *   guard specifically because a truthiness test would read the legitimate
+     *   `false` as missing — and defaulting a missing value to `false` converts
+     *   an all-day event into a midnight-to-midnight timed one.
+     * - `description` is optional and nullable both ways, so absent or null is a
+     *   genuinely empty description.
+     */
+    private currentState;
+    /**
+     * The full-state fields plus the carve-out seeds the `editEntry` callback can
+     * read.
+     *
+     * `url` is seeded from the response's **`join_url`**, not its `url`: the
+     * latter is the entry's own Basecamp API URL, written by
+     * `recordings/_recording` before the entry partial renders. Echoing it into
+     * the request's `url` would write the API URL into the join link.
+     *
+     * `updateEntry` deliberately does not come through here. It never seeds a
+     * carve-out, so validating `participants` for it would refuse a write that
+     * does not depend on them.
+     */
+    private currentFields;
+    /**
+     * GETs the entry and checks the envelope before any field is read.
+     *
+     * A successful GET can still return a scalar, an array or null; reading a
+     * property off `null` throws a raw `TypeError` instead of the documented
+     * statusless `api_error`, and reading one off an array or string silently
+     * yields `undefined`, which the field guards would then take at face value.
+     */
+    private readEntry;
+    /**
+     * PUTs the full writable state via `replaceEntry`, plus whichever carve-outs
+     * the caller addressed.
+     *
+     * The five full-state fields are always named, 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 BC3's clear-by-default and read as an accident rather than an
+     * intent. The carve-outs are the mirror image: an unaddressed one is absent
+     * from `carveOuts`, so the generated request builder leaves it `undefined`
+     * and it never reaches the wire.
+     */
+    private putEntry;
+}
+//# sourceMappingURL=schedules-extensions.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"schedules-extensions.d.ts","sourceRoot":"","sources":["../../src/services/schedules-extensions.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,IAAI,yBAAyB,EAAE,MAAM,oCAAoC,CAAC;AACnG,OAAO,KAAK,EAEV,aAAa,EACd,MAAM,oCAAoC,CAAC;AAuB5C;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,WAAW,0BAA0B;IACzC,6DAA6D;IAC7D,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,wFAAwF;IACxF,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,6EAA6E;IAC7E,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,sEAAsE;IACtE,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB;;;;;;;OAOG;IACH,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B;;;;;;;OAOG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,oGAAoG;IACpG,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB;;;OAGG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,mBAAmB;IAClC,iFAAiF;IACjF,OAAO,EAAE,MAAM,CAAC;IAChB,iEAAiE;IACjE,QAAQ,EAAE,MAAM,CAAC;IACjB,+DAA+D;IAC/D,MAAM,EAAE,MAAM,CAAC;IACf,uDAAuD;IACvD,WAAW,EAAE,MAAM,CAAC;IACpB,6CAA6C;IAC7C,MAAM,EAAE,OAAO,CAAC;IAChB,yFAAyF;IACzF,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,uFAAuF;IACvF,GAAG,EAAE,MAAM,CAAC;IACZ,uEAAuE;IACvE,WAAW,EAAE,OAAO,CAAC;IACrB;;;OAGG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AASD;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,qBAAa,gBAAiB,SAAQ,yBAAyB;IAC7D;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA4BG;IACG,WAAW,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,0BAA0B,GAAG,OAAO,CAAC,aAAa,CAAC;IAgC3F;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAkCG;IACG,SAAS,CACb,OAAO,EAAE,MAAM,EACf,EAAE,EAAE,CAAC,CAAC,EAAE,mBAAmB,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,GACnD,OAAO,CAAC,aAAa,CAAC;IA0BzB;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA4BG;YACW,YAAY;IAW1B;;;;;;;;;;;;OAYG;YACW,aAAa;IAc3B;;;;;;;OAOG;YACW,SAAS;IAQvB;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,QAAQ;CAcjB"}