@k9o/core 1.1.1 → 1.3.0

package/src/projects.ts

@@ -5,51 +5,87 @@
  * `discovery.ts`):
  *   - `client.projects.list()`           → GET    /projects
  *   - `client.projects.create({...})`    → POST   /projects
- *   - `client.projects.get(slug)`        → GET    /@<projectSlug>/project
- *   - `client.projects.update(slug,...)` → PATCH  /@<projectSlug>/project
+ *   - `client.projects.get(slug)`        → GET    /projects/<projectSlug>
+ *   - `client.projects.update(slug,...)` → PATCH  /projects/<projectSlug>
  *
- * The `list` + `create` operations operate org-plane and require
- * `orgSlug` to be bound on the client (or the bearer token to carry
- * an org context). The `get` + `update` operations
- * operate member-plane and use the project slug.
+ * All four operations are org-plane: the client needs an org context
+ * (an `orgSlug` or a bearer token that carries one). Input property
+ * names are the gateway's body property names.
  *
- * Per: all methods throw KError on non-2xx.
+ * All methods throw KError on non-2xx.
  */
 
 import { request, type HttpClientConfig } from "./http.ts";
-import { orgPath, projectPath, validateSlug } from "./url-grammar.ts";
+import { orgPath, validateSlug } from "./url-grammar.ts";
 import type { Envelope } from "./envelope.ts";
 
 /**
- * Project shape. Fields are typed per the canonical shape;
- * the gateway may return additional fields that this type doesn't
- * narrow — those are accessible via `as unknown as` widening.
+ * Project record, as the gateway returns it. Field names are passed through unchanged.
+ * Lists and creates also carry `capabilities`; lists add `accessLevel`.
  */
 export type Project = {
   /** `proj_<base62>`. */
   id: string;
   slug: string;
-  name: string;
-  custodyMode: "managed" | "byok" | "hyok";
-  createdAt: string;
-  updatedAt: string | null;
   orgId: string;
+  displayName: string;
+  description: string | null;
+  productScope: string;
+  /** Region code of the project's data. */
+  region: string;
+  custodyMode: "PLATFORM_MANAGED" | "SKR" | "BYOK" | "HYOK";
+  /** `provisioning` while the project is being set up, then `active`; other values may appear. */
+  status: string;
+  /** The caller's role on the project, or `null` when the caller is not a member. */
+  role: string | null;
+  deletedAt: string | null;
+  createdAt: string;
+  /** Soft-delete retention window in days. */
+  softDeleteRetentionDays: number;
+  /** Regions the project's data may live in; `[region]` for a single-region project. */
+  residencySet: ReadonlyArray<string>;
+  /** `"strict"`, or `{ fallbackRegion }` when a catch-all region is set. */
+  residencyPolicy: "strict" | { fallbackRegion: string };
+  processingContexts: ReadonlyArray<string>;
+  /** Present on list and create responses: what the caller may write. */
+  capabilities?: { authFlows: { write: boolean }; authProviders: { write: boolean } } | undefined;
+  /** Present on list responses: `member` or `locked`. */
+  accessLevel?: "member" | "locked" | undefined;
 };
 
 /**
  * Project-creation input.
  */
 export type CreateProjectInput = {
-  slug: string;
-  name: string;
-  custodyMode?: "managed" | "byok" | "hyok" | undefined;
+  /** Display name (1 to 128 characters). Required. */
+  displayName: string;
+  /** URL slug (lowercase); the gateway derives one from `displayName` when omitted. */
+  slug?: string | undefined;
+  productScope?: "core" | "kibo" | undefined;
+  /** Region code of the project's data. */
+  region?: string | undefined;
+  defaultProjectRegion?: string | undefined;
+  custodyMode?: "PLATFORM_MANAGED" | "SKR" | "BYOK" | "HYOK" | undefined;
+  processingContexts?: ReadonlyArray<string> | undefined;
+  execSeamConfined?: boolean | undefined;
+  showroomVertical?: string | undefined;
+  persona?: string | undefined;
+  showroomLocale?: { code: string; currency: string; moneyScale: number } | undefined;
+  /** Makes a retried create return the first result instead of a second project. */
+  idempotencyKey?: string | undefined;
 };
 
 /**
  * Project-update patch.
  */
 export type UpdateProjectInput = {
-  name?: string;
+  slug?: string | undefined;
+  displayName?: string | undefined;
+  description?: string | null | undefined;
+  region?: string | undefined;
+  productScope?: string | undefined;
+  softDeleteRetentionDays?: number | undefined;
+  processingContexts?: ReadonlyArray<string> | undefined;
 };
 
 /**
@@ -73,7 +109,7 @@ export function makeProjectsNamespace(config: HttpClientConfig) {
      * Create a new project under the caller's active org.
      */
     async create(input: CreateProjectInput): Promise<Envelope<Project>> {
-      validateSlug(input.slug, "project");
+      if (input.slug !== undefined) validateSlug(input.slug, "project");
       return request<Project>(config, {
         method: "POST",
         path: orgPath("projects"),
@@ -88,7 +124,7 @@ export function makeProjectsNamespace(config: HttpClientConfig) {
       validateSlug(slug, "project");
       return request<Project>(config, {
         method: "GET",
-        path: projectPath(slug, "project"),
+        path: orgPath(`projects/${slug}`),
       });
     },
 
@@ -99,7 +135,7 @@ export function makeProjectsNamespace(config: HttpClientConfig) {
       validateSlug(slug, "project");
       return request<Project>(config, {
         method: "PATCH",
-        path: projectPath(slug, "project"),
+        path: orgPath(`projects/${slug}`),
         body: patch,
       });
     },

package/src/realtime.ts

@@ -7,33 +7,28 @@
  * yielding `RealtimeEvent`s — the caller writes idiomatic
  * `for await (const event of client.realtime.subscribe(topic)) { ... }`.
  *
- * Per `feedback_sdk_abstracted_primitive_default_to_richer_interaction.md`
- * +: the SDK chooses the transport (WebSocket primary → SSE
- * → poll), transparently. SPLIT (polling) is the SDK-internal fallback
- * when WebSocket / SSE are unavailable — NOT a consumer-side design
- * choice. The consumer sees one uniform async iterable regardless.
+ * Transport: SSE over `GET /@<slug>/realtime/subscribe`. The gateway
+ * serves no WebSocket upgrade and no durable replay, so neither is
+ * offered; after an `event: resync` frame the client re-reads current
+ * state from the data plane and resubscribes.
  *
- * Wire mapping (project-plane;):
- *   - subscribe → GET  /@<slug>/realtime/subscribe?topic=<t>&filter=<jsonb> (WS/SSE upgrade)
- *   - replay    → POST /@<slug>/realtime/replay  { topic, fromSequence, untilSequence?, limit? }
+ * Wire mapping (project-plane):
+ *   - subscribe → GET  /@<slug>/realtime/subscribe?topic=<t>&filter=<jsonb>  (SSE)
  *
- * Per, `filter` + RLS compose (filter narrows, RLS gates).
- * Per, surfaces no new codes — reuses K9O_INVALID_FILTER +
- * K9O_SUBSCRIPTION_LIMIT_EXCEEDED + K9O_TIER_FEATURE_GATED.
+ * `filter` + RLS compose (filter narrows, RLS gates). Surfaces
+ * K9O_INVALID_FILTER, K9O_SUBSCRIPTION_LIMIT_EXCEEDED and K9O_TIER_FEATURE_GATED.
  */
 
-import { request, requestStream, type HttpClientConfig } from "./http.ts";
+import { requestStream, type HttpClientConfig } from "./http.ts";
 import { projectPath } from "./url-grammar.ts";
-import { KError } from "./kerror.ts";
-import type { Envelope } from "./envelope.ts";
 import { parseSseStream } from "./internal/sse.ts";
 
 // ----------------------------------------------------------------------
-// Topic catalogue (closed 6-family enum)
+// Topic catalogue 
 // ----------------------------------------------------------------------
 
 /**
- * The 6 closed subscription topic families. Concrete
+ * The 6 closed subscription topic families . Concrete
  * topic strings carry a dynamic segment (collection name, resource id,
  * event family) — use `realtimeTopic.*` builders to construct them.
  */
@@ -49,7 +44,7 @@ export type RealtimeTopicFamily =
 export type RealtimeTopic = string;
 
 /**
- * Typed builders for the 6 topic families. Prefer these
+ * Typed builders for the 6 topic families . Prefer these
  * over hand-built strings for compile-time family safety.
  */
 export const realtimeTopic = {
@@ -83,16 +78,14 @@ export const realtimeTopic = {
 // Event + filter shapes
 // ----------------------------------------------------------------------
 
-/** Per-topic filter predicate (vocabulary). */
+/** Per-topic filter predicate . */
 export type RealtimeFilter = Record<string, unknown>;
 
-/** A single realtime event delivered on a subscription. */
+/** A single realtime event, as the gateway frames it (wire spelling). */
 export type RealtimeEvent<T = unknown> = {
   topic: RealtimeTopic;
   /** Event type within the topic family (e.g. `row_inserted`, `workflow.run.completed`). */
-  type: string;
-  /** Monotonic sequence number — use as `fromSequence` for replay catch-up. */
-  sequence: number;
+  eventType: string;
   payload: T;
   occurredAt: string;
 };
@@ -101,35 +94,15 @@ export type SubscribeOptions = {
   filter?: RealtimeFilter;
   /** Abort the subscription (closes the underlying transport). */
   signal?: AbortSignal;
-  /**
-   * Force a transport instead of the WebSocket → SSE → poll cascade.
-   * Mainly for tests + constrained runtimes. Omit for production —
-   * the SDK picks the richest available transport.
-   */
-  transport?: RealtimeTransportKind;
-  /** Poll-transport interval in ms (default 2000). Only used when polling. */
-  pollIntervalMs?: number;
 };
 
-export type RealtimeTransportKind = "websocket" | "sse" | "poll";
-
 /**
  * A live subscription. It is itself an async iterable (`for await`) and
- * exposes `close()` for explicit teardown + `transport` for diagnostics.
+ * exposes `close()` for explicit teardown.
  */
 export type RealtimeSubscription<T = unknown> = AsyncIterable<RealtimeEvent<T>> & {
   /** Stop the subscription + release the underlying transport. */
   close(): void;
-  /** The transport actually selected (post-fallback). */
-  readonly transport: RealtimeTransportKind;
-};
-
-export type ReplayInput = {
-  topic: RealtimeTopic;
-  filter?: RealtimeFilter;
-  fromSequence: number;
-  untilSequence?: number;
-  limit?: number;
 };
 
 function requireProjectSlug(config: HttpClientConfig): string {
@@ -139,90 +112,7 @@ function requireProjectSlug(config: HttpClientConfig): string {
   return config.projectSlug;
 }
 
-/** Pick the richest transport available in this runtime. */
-function selectTransport(forced?: RealtimeTransportKind): RealtimeTransportKind {
-  if (forced) return forced;
-  if (typeof (globalThis as { WebSocket?: unknown }).WebSocket === "function") return "websocket";
-  // SSE rides on fetch streaming, which the http layer already requires.
-  return "sse";
-}
-
-/** Convert an http(s) baseUrl to a ws(s) URL for the WebSocket transport. */
-function toWebSocketUrl(baseUrl: string, path: string, query: Record<string, string>): string {
-  const trimmed = baseUrl.endsWith("/") ? baseUrl.slice(0, -1) : baseUrl;
-  const wsBase = trimmed.replace(/^http/, "ws");
-  const qs = new URLSearchParams(query).toString();
-  return `${wsBase}${path}${qs ? `?${qs}` : ""}`;
-}
-
-/** WebSocket transport — primary. Bridges socket → async queue. */
-async function* websocketTransport<T>(
-  config: HttpClientConfig,
-  topic: RealtimeTopic,
-  options: SubscribeOptions,
-  closed: { value: boolean },
-): AsyncGenerator<RealtimeEvent<T>, void, void> {
-  const slug = requireProjectSlug(config);
-  const query: Record<string, string> = { topic };
-  if (options.filter) query.filter = JSON.stringify(options.filter);
-  if (config.apiKey) query.access_token = config.apiKey; // WS can't set Authorization header
-  const url = toWebSocketUrl(config.baseUrl, projectPath(slug, "realtime/subscribe"), query);
-  const WS = (globalThis as { WebSocket: new (url: string) => WebSocket }).WebSocket;
-  const socket = new WS(url);
-
-  const queue: RealtimeEvent<T>[] = [];
-  let resolveNext: (() => void) | null = null;
-  let socketClosed = false;
-  let socketError: Error | null = null;
-
-  const wake = () => {
-    if (resolveNext) {
-      resolveNext();
-      resolveNext = null;
-    }
-  };
-  socket.onmessage = (ev: MessageEvent) => {
-    try {
-      queue.push(JSON.parse(typeof ev.data === "string" ? ev.data : String(ev.data)) as RealtimeEvent<T>);
-    } catch {
-      /* ignore malformed frame */
-    }
-    wake();
-  };
-  socket.onerror = () => {
-    socketError = new Error("realtime websocket transport error");
-    wake();
-  };
-  socket.onclose = () => {
-    socketClosed = true;
-    wake();
-  };
-  options.signal?.addEventListener("abort", () => socket.close());
-
-  try {
-    while (!closed.value) {
-      if (queue.length > 0) {
-        yield queue.shift() as RealtimeEvent<T>;
-        continue;
-      }
-      if (socketClosed) {
-        if (socketError) throw socketError;
-        return;
-      }
-      await new Promise<void>((resolve) => {
-        resolveNext = resolve;
-      });
-    }
-  } finally {
-    try {
-      socket.close();
-    } catch {
-      /* already closed */
-    }
-  }
-}
-
-/** SSE transport — fallback. Rides on fetch streaming. */
+/** SSE transport — rides on fetch streaming. `resync` control frames are not events and are skipped. */
 async function* sseTransport<T>(
   config: HttpClientConfig,
   topic: RealtimeTopic,
@@ -240,73 +130,33 @@ async function* sseTransport<T>(
   });
   for await (const event of parseSseStream<RealtimeEvent<T>>(response.body as ReadableStream<Uint8Array>)) {
     if (closed.value || options.signal?.aborted) return;
+    if (typeof (event as { eventType?: unknown }).eventType !== "string") continue;
     yield event;
   }
 }
 
-/** Poll transport — last-resort fallback (SPLIT, SDK-internal). */
-async function* pollTransport<T>(
-  config: HttpClientConfig,
-  topic: RealtimeTopic,
-  options: SubscribeOptions,
-  closed: { value: boolean },
-): AsyncGenerator<RealtimeEvent<T>, void, void> {
-  const slug = requireProjectSlug(config);
-  const interval = options.pollIntervalMs ?? 2000;
-  let cursor = 0;
-  while (!closed.value && !options.signal?.aborted) {
-    const { data } = await request<ReadonlyArray<RealtimeEvent<T>>>(config, {
-      method: "POST",
-      path: projectPath(slug, "realtime/replay"),
-      body: { topic, filter: options.filter, fromSequence: cursor },
-    });
-    for (const event of data ?? []) {
-      if (closed.value || options.signal?.aborted) return;
-      cursor = Math.max(cursor, event.sequence + 1);
-      yield event;
-    }
-    if (closed.value || options.signal?.aborted) return;
-    await new Promise<void>((resolve) => setTimeout(resolve, interval));
-  }
-}
-
 export function makeRealtimeNamespace(config: HttpClientConfig) {
   return {
     /**
      * Subscribe to a topic. Returns a `RealtimeSubscription` — an async
-     * iterable of `RealtimeEvent`s. The SDK selects the richest available
-     * transport (WebSocket → SSE → poll); the caller's
-     * `for await` loop is transport-agnostic.
+     * iterable of `RealtimeEvent`s over SSE.
      *
      * ```ts
      * const sub = client.realtime.subscribe(
      *   realtimeTopic.dashboardRefresh("dsh_abc"),
      * );
      * for await (const event of sub) {
-     *   if (event.type === "dashboard.widget.data_refreshed") rerender(event.payload);
+     *   if (event.eventType === "dashboard.widget.data_refreshed") rerender(event.payload);
      * }
      * ```
      */
     subscribe<T = unknown>(topic: RealtimeTopic, options: SubscribeOptions = {}): RealtimeSubscription<T> {
       requireProjectSlug(config);
-      const transport = selectTransport(options.transport);
       const closed = { value: false };
-
-      const iterate = (): AsyncGenerator<RealtimeEvent<T>, void, void> => {
-        switch (transport) {
-          case "websocket":
-            return websocketTransport<T>(config, topic, options, closed);
-          case "poll":
-            return pollTransport<T>(config, topic, options, closed);
-          case "sse":
-          default:
-            return sseTransport<T>(config, topic, options, closed);
-        }
-      };
+      const iterate = (): AsyncGenerator<RealtimeEvent<T>, void, void> => sseTransport<T>(config, topic, options, closed);
 
       let active: AsyncGenerator<RealtimeEvent<T>, void, void> | null = null;
       return {
-        transport,
         [Symbol.asyncIterator]() {
           active = iterate();
           return active;
@@ -317,34 +167,5 @@ export function makeRealtimeNamespace(config: HttpClientConfig) {
         },
       };
     },
-
-    /**
-     * One-shot historical replay — catch up on missed
-     * events from `fromSequence`. Capped at 10k events server-side;
-     * paginate via the returned events' `sequence`. Use the highest
-     * `sequence` you've seen as the next `fromSequence`.
-     */
-    async replay<T = unknown>(input: ReplayInput): Promise<Envelope<ReadonlyArray<RealtimeEvent<T>>>> {
-      const slug = requireProjectSlug(config);
-      if (!Number.isInteger(input.fromSequence) || input.fromSequence < 0) {
-        throw new KError({
-          code: "K9O_INVALID_FILTER",
-          message: "replay fromSequence must be a non-negative integer",
-          context: { fromSequence: input.fromSequence },
-          recommendation: "Pass the highest sequence number you have already observed (or 0 to replay from the start).",
-        });
-      }
-      return request(config, {
-        method: "POST",
-        path: projectPath(slug, "realtime/replay"),
-        body: {
-          topic: input.topic,
-          filter: input.filter,
-          fromSequence: input.fromSequence,
-          untilSequence: input.untilSequence,
-          limit: input.limit,
-        },
-      });
-    },
   };
 }

package/src/region.ts

@@ -1,5 +1,85 @@
 /**
- * Regional host resolution lives in `@k9o/gate` (which `@k9o/core` composes), so the Gate client and the core client
- * share one implementation of the probe and of the `Location` validation. See `packages/gate/src/region.ts`.
+ * Regional host resolution.
+ *
+ * A region-free org host `<org>.api.<rest>` (or `<org>.api-staging.<rest>`) redirects GET/HEAD only and REFUSES a
+ * request that carries a body, an `Authorization` header or a cookie (`400 K9O_INVALID_REQUEST_SHAPE`,
+ * `region_free_host_takes_no_credentials`), so credentials must go to `<org>.api-<rgn>.<rest>`. The client learns the
+ * region with ONE unauthenticated `HEAD` to the configured host, takes the `308` `Location`, and caches the regional
+ * origin.
+ *
+ * Nothing here knows an apex. The host comes from the configured baseUrl; `<rest>` is whatever follows the second
+ * label, so a public-cloud, internal-apex, air-gapped or localhost deployment all work. Properties:
+ *   - Only a host shaped `<org>.api.<rest>` / `<org>.api-staging.<rest>` is probed. A regional, single-label, IP,
+ *     localhost or any other baseUrl is used exactly as given.
+ *   - The probe carries NO credential and none of the configured default headers (they may hold one).
+ *   - The `Location` is trusted only if it is `https`, has no userinfo/port, and its host is exactly the SAME org and
+ *     SAME remainder with a 4-character region code appended to the second label. Anything else is ignored and the
+ *     configured baseUrl stays, so a hostile redirect can never receive a credential.
+ *   - Not a redirect, or any failure: the configured baseUrl stays and the server's own refusal, if any, is what the
+ *     caller sees. A definite answer is cached for the life of the client's config; a network failure is not cached.
  */
-export { resolveRegionalOrigin, regionalOriginFromLocation, type RegionConfig } from "@k9o/gate";
+
+import { parseApiHost } from "./url-grammar.ts";
+
+/** The slice of a client config this module needs. */
+export type RegionConfig = { baseUrl: string; fetch?: typeof globalThis.fetch | undefined };
+
+const cache = new WeakMap<RegionConfig, Promise<string>>();
+
+/** The regional origin a `Location` may name for `host`, or null if it is not exactly that. Pure. */
+export function regionalOriginFromLocation(host: string, location: string, base: string): string | null {
+  const from = parseApiHost(host);
+  if (from === null || from.orgSlug === null || from.region !== null) return null;
+  let u: URL;
+  try {
+    u = new URL(location, base);
+  } catch {
+    return null;
+  }
+  if (u.protocol !== "https:" || u.username !== "" || u.password !== "" || u.port !== "") return null;
+  const to = parseApiHost(u.hostname);
+  if (to === null || to.region === null) return null;
+  if (to.orgSlug !== from.orgSlug || to.family !== from.family || to.apex !== from.apex) return null;
+  return `https://${u.hostname}`;
+}
+
+async function probe(config: RegionConfig): Promise<{ origin: string; cacheable: boolean }> {
+  const fetchImpl = config.fetch ?? globalThis.fetch;
+  const configured = config.baseUrl;
+  if (typeof fetchImpl !== "function") return { origin: configured, cacheable: false };
+  let host: string;
+  try {
+    host = new URL(configured).hostname;
+  } catch {
+    return { origin: configured, cacheable: true };
+  }
+  const parsedHost = parseApiHost(host);
+  if (parsedHost === null || parsedHost.orgSlug === null || parsedHost.region !== null) return { origin: configured, cacheable: true };
+  try {
+    const res = await fetchImpl(`${configured.replace(/\/+$/, "")}/`, {
+      method: "HEAD",
+      redirect: "manual",
+      headers: { accept: "*/*" },
+    } as Parameters<typeof fetchImpl>[1]);
+    if (res.status === 308) {
+      const loc = res.headers.get("location");
+      const origin = loc === null ? null : regionalOriginFromLocation(host, loc, configured);
+      if (origin !== null) return { origin, cacheable: true };
+    }
+    return { origin: configured, cacheable: true };
+  } catch {
+    return { origin: configured, cacheable: false };
+  }
+}
+
+/** The origin requests for this client go to: the cached regional origin once learned, else the configured baseUrl. */
+export function resolveRegionalOrigin(config: RegionConfig): Promise<string> {
+  const hit = cache.get(config);
+  if (hit !== undefined) return hit;
+  const p = probe(config).then((r) => {
+    if (!r.cacheable) cache.delete(config);
+    return r.origin;
+  });
+  cache.set(config, p);
+  return p;
+}

package/src/storage-buckets.ts

@@ -4,7 +4,8 @@
  * `storage-locations.ts` and is unchanged.
  *
  * Bucket names are logical: the platform resolves them to a physical store, so a developer never sees a
- * physical bucket or key. Signed URLs require an explicit `expiresIn` (no default, max 7 days).
+ * physical bucket or key. Signed URLs require an explicit `expiresIn` (no default). The gateway accepts 1 to 604800 seconds but never
+ * signs for longer than 900 seconds, and the answer's `expiresIn` is the lifetime it actually used.
  *
  * What is NOT here yet, by design: a signed PUT (a method- and content-type-bound upload URL). The gateway has
  * no route for it; uploads go through the multipart `upload` below.
@@ -18,14 +19,15 @@ import type { Envelope } from "./envelope.ts";
 /** A bucket. */
 export type StorageBucket = {
   name: string;
-  /** `true` removes the authentication requirement on GET; per-object access policies still apply. */
+  /** Stored and returned, not enforced: setting it does not yet change who can read objects. */
   public: boolean;
   /** Bytes; `null` = no limit. */
   fileSizeLimit: number | null;
   /** MIME allow-list; empty = any. */
   allowedMimeTypes: string[];
+  /** Stored and returned, not enforced: the platform does not keep object versions yet. */
   versioning: boolean;
-  /** Lifecycle auto-expiry in days; `null` = never. */
+  /** Stored and returned, not enforced: nothing deletes objects after this many days yet. `null` = never. */
   deleteAfterDays: number | null;
   createdAt: string;
   updatedAt: string;
@@ -37,10 +39,13 @@ export type StorageBucket = {
 
 /** Options for `createBucket`. The bucket name is the first argument (3 to 63 chars, lowercase, digits, hyphens). */
 export type CreateBucketOptions = {
+  /** Stored, not enforced yet (see `StorageBucket.public`). */
   public?: boolean;
   fileSizeLimit?: number;
   allowedMimeTypes?: string[] | null;
+  /** Stored, not enforced yet. */
   versioning?: boolean;
+  /** Stored, not enforced yet. */
   deleteAfterDays?: number;
   /** Link the bucket to one of the project's storage locations (see `client.storage.locations`). */
   byosBindingId?: string;
@@ -48,10 +53,13 @@ export type CreateBucketOptions = {
 
 /** Fields you may change on a bucket. `null` clears a limit; `allowedMimeTypes: null` allows any type. */
 export type UpdateBucketOptions = {
+  /** Stored, not enforced yet. */
   public?: boolean;
   fileSizeLimit?: number | null;
   allowedMimeTypes?: string[] | null;
+  /** Stored, not enforced yet. */
   versioning?: boolean;
+  /** Stored, not enforced yet. */
   deleteAfterDays?: number | null;
   /** `null` unlinks the bucket from its storage location. */
   byosBindingId?: string | null;
@@ -74,12 +82,16 @@ export type UploadOptions = {
 };
 
 export type SignedUrlOptions = {
-  /** Seconds, required: 1 to 604800 (7 days). There is deliberately no default. */
+  /**
+   * Seconds, required: 1 to 604800. There is deliberately no default. The gateway clamps the lifetime to 900
+   * seconds (15 minutes); read `expiresIn` in the answer for the lifetime you got.
+   */
   expiresIn: number;
   /** `true` makes the download an attachment (`Content-Disposition: attachment`). */
   download?: boolean;
 };
 
+/** `expiresIn` is the lifetime the gateway used: at most 900 seconds, even when you asked for more. */
 export type SignedUrl = { signedUrl: string; expiresIn: number };
 export type RemovedObject = { bucket: string; path: string; deleted: boolean };
 export type DeletedBucket = { name: string; deleted: true; objectsDeleted: number };
@@ -172,7 +184,7 @@ export function makeBucketHandle(config: HttpClientConfig, bucket: string) {
     },
 
     /**
-     * A pre-authenticated GET URL for one object. `POST …/objects/sign`. `expiresIn` is required.
+     * A pre-authenticated GET URL for one object. `POST …/objects/sign`. `expiresIn` is required; the URL lives at most 900 seconds.
      * (A signed PUT is not offered: the gateway has no route for it yet.)
      */
     async createSignedUrl(path: string, options: SignedUrlOptions): Promise<Envelope<SignedUrl>> {