// Backlit runtime SDK — ambient type surface for `window.backlit`.
//
// This is the canonical MACHINE contract for the global the hosted bundle
// (`<script src="https://sdk.backlit.run/sdk/v1/sdk.js">`) attaches to
// `window`. It is hand-authored but kept in lockstep with the SDK source in
// `sdk/src/*` — every type below is derived from those modules (the prose
// reference at /sdk can drift; the source and this file cannot). If you change
// a signature in `sdk/src`, change it here and run `task sdk:dts:check`.
//
// It is a *script-style* declaration file (no top-level import/export), so it
// applies globally the moment a consumer's TypeScript project references it —
// matching how the bundle works at runtime. Drop it next to your code, or add
// `/// <reference types="./sdk.d.ts" />`, and `window.backlit` is fully typed.
//
// Hosted alongside the bundle at `https://sdk.backlit.run/sdk/v1/sdk.d.ts`
// (and mirrored at `https://sdk.backlit.run/sdk.d.ts`).

// ===========================================================================
// Identity
// ===========================================================================

/**
 * Access level of a signed-in user on a Private glow — the lowercase wire
 * enum. A `"viewer"` is blocked from glow-shared writes (`data.put` /
 * `data.delete`); `userdata.*`, `records.*`, and `capture.*` writes are
 * unaffected.
 */
type Permission = "admin" | "user" | "viewer";

/**
 * The signed-in user, as returned by {@link AuthNamespace.me} (or one row of
 * {@link AuthNamespace.users}). Every field is a string — absent
 * `uid`/`name`/`mobile` decode to `""`, and an absent/unrecognized
 * `permission` to `""` (never `null`/`undefined`). `name`/`email`/`mobile`
 * are user-controlled display strings: escape them before inserting into HTML.
 */
interface BacklitUser {
  /** Stable per-user id; survives an email change and keys the `userdata` silo. */
  readonly uid: string;
  /** Display name, or `""` if unset. */
  readonly name: string;
  /** Verified email, or `""` if the user signed in without one. */
  readonly email: string;
  /** Mobile number, or `""` if unset. */
  readonly mobile: string;
  /** Permission level, or `""` for a legacy/unknown session. */
  readonly permission: Permission | "";
}

// ===========================================================================
// Stored-value shapes
// ===========================================================================

/** The value at a key: the bytes, the stored content-type, and the body CRC32C. */
interface StoredValue {
  /** The raw bytes (the browser auto-decodes any transport compression). */
  readonly value: Blob;
  /** The content-type the value was written with. */
  readonly contentType: string;
  /** Base64-encoded Castagnoli CRC32C of the body. `""` if the server omitted it. */
  readonly crc32c: string;
}

/** The result of a `get` on `data` / `userdata`. Identical to {@link StoredValue}. */
type BlobResult = StoredValue;

/** The result of a `put` / `capture.update`: the body's integrity hash. */
interface PutResult {
  /** Base64-encoded Castagnoli CRC32C of the body just stored. */
  readonly crc32c: string;
}

/**
 * Outcome of a compare-and-swap write ({@link DataNamespace.putIfMatch}). A CRC
 * mismatch (you lost the race) is a NORMAL result, not an error — narrow on
 * `.matched`. Real failures (`not_found`, `forbidden`, `quota_exceeded`, …)
 * still throw {@link BacklitError}.
 */
type PutIfMatchResult =
  | { readonly matched: true; readonly crc32c: string }
  | { readonly matched: false; readonly witness: StoredValue };

/** One entry of a `data.list` / `userdata.list` response. */
interface ListEntry {
  /** The SDK-visible key. */
  readonly key: string;
  /** Base64-encoded Castagnoli CRC32C of the body (`""` if omitted). */
  readonly crc32c: string;
  /** The stored content-type (`""` if omitted). */
  readonly contentType: string;
  /** The body's logical size in bytes (`0` if omitted). */
  readonly size: number;
}

/**
 * Optional pagination controls for every `list()` surface
 * (`data` / `userdata` / `records` / `capture`).
 */
interface ListOptions {
  /**
   * Opaque continuation token. Pass a prior page's {@link ListPage.next} to
   * fetch the following page; omit (or `""`) for the first page.
   */
  cursor?: string;
  /**
   * Requested page size, clamped server-side to `[1, 1000]` (omitted ⇒ the
   * server default of 500). An over-range value is clamped, never rejected.
   */
  limit?: number;
}

/**
 * One bounded page returned by every `list()` surface: the entries plus an
 * opaque `next` cursor. Paginate by re-calling `list(prefix, { cursor: next })`
 * until `next` is `""` (the listing is exhausted).
 */
interface ListPage<E> {
  /** This page's entries (the per-entry shape — unchanged from the flat array). */
  readonly items: readonly E[];
  /** The cursor for the next page, or `""` when exhausted. */
  readonly next: string;
}

// ===========================================================================
// Batch-read shapes (data/userdata/records getBatch / getBatchJSON)
// ===========================================================================

/**
 * Optional pagination controls for every `getBatch()` / `getBatchJSON()`
 * surface (`data` / `userdata` / `records`). Structurally like
 * {@link ListOptions}, but the page-size clamp differs — hence a dedicated type.
 */
interface GetBatchOptions {
  /**
   * Opaque continuation token. Pass a prior page's {@link ListPage.next} to
   * fetch the following page; omit (or `""`) for the first page. `next` is the
   * **sole** continuation signal — a page can end early even when more entries
   * exist (see below), so always paginate on `next`, never on item count.
   */
  cursor?: string;
  /**
   * Requested page size, clamped server-side to `[1, 500]` (omitted ⇒ the
   * default of 100). An over-range value is clamped, never rejected. A page may
   * still hold **fewer** entries than requested: the server also caps each
   * response at a per-response value budget (about 10 MiB by default) and ends
   * the page early, with `next` pointing at the first entry it did not include.
   */
  limit?: number;
}

/**
 * One entry of a `data.getBatch` / `userdata.getBatch` response — the value-
 * bearing superset of {@link ListEntry}. Discriminated on `omitted` (narrow on
 * it like {@link PutIfMatchResult}'s `.matched` — a **normal** outcome, not an
 * error):
 *  - **included** (`omitted` absent/`false`): `value` is the {@link Blob} —
 *    a zero-byte Blob is a real empty value, never omission;
 *  - **metadata-only** (`omitted: true`): `value` is absent and `reason` (when
 *    present) says why. A single value larger than the whole per-response budget
 *    arrives this way with `reason: "too_large"`; fetch it with a plain `get`.
 *
 * `reason` is an **open vocabulary** — tolerate unknown values. The only wire
 * value today is `"too_large"`.
 */
type BatchEntry = ListEntry & (
  | { readonly omitted?: false; readonly value: Blob }
  | { readonly omitted: true; readonly value?: never; readonly reason?: string }
);

/** A {@link BatchEntry} plus the record's owner uid — one `records.getBatch` row. */
type RecordBatchEntry = BatchEntry & { readonly owner: string };

// ===========================================================================
// JSON convenience shapes
// ===========================================================================

/** What `getJSON` / `updateJSON` resolve to: the parsed value plus its body CRC32C. */
interface JSONResult<T> {
  /** The parsed value. */
  readonly value: T;
  /** Base64-encoded Castagnoli CRC32C of the stored body — feeds `putJSONIfMatch`. */
  readonly crc32c: string;
}

/**
 * JSON analogue of {@link PutIfMatchResult}: on a mismatch the witness carries
 * an already-parsed `value` (no Blob to decode).
 */
type PutJSONIfMatchResult<T> =
  | { readonly matched: true; readonly crc32c: string }
  | { readonly matched: false; readonly witness: JSONResult<T> };

/** Options for `updateJSON`. */
interface UpdateJSONOptions {
  /** Max compare-and-swap attempts before throwing `conflict`. Default 6. */
  maxAttempts?: number;
}

// ===========================================================================
// Records-surface shapes (window.backlit.records) — base shapes plus `owner`
// ===========================================================================

/** A {@link StoredValue} plus the record's owner uid (creator). */
type RecordResult = StoredValue & { readonly owner: string };

/** A {@link ListEntry} plus the record's owner uid. */
type RecordListEntry = ListEntry & { readonly owner: string };

/** {@link PutIfMatchResult} for records — both arms surface the `owner` uid. */
type RecordPutIfMatchResult =
  | { readonly matched: true; readonly crc32c: string; readonly owner: string }
  | { readonly matched: false; readonly witness: RecordResult };

/** {@link JSONResult} for records — carries the record's owner uid. */
type RecordJSONResult<T> = JSONResult<T> & { readonly owner: string };

/** {@link PutJSONIfMatchResult} for records — both arms surface the `owner` uid. */
type RecordPutJSONIfMatchResult<T> =
  | { readonly matched: true; readonly crc32c: string; readonly owner: string }
  | { readonly matched: false; readonly witness: RecordJSONResult<T> };

/**
 * One entry of a `data.getBatchJSON` / `userdata.getBatchJSON` response — the
 * {@link BatchEntry} shape with each included value already `JSON.parse`d to
 * `T` (parsing is content-type-agnostic, matching `getJSON`). Discriminated on
 * `omitted` (narrow on it — a **normal** outcome, not an error):
 *  - **included** (`omitted` absent/`false`): `value` is the parsed `T`. A JSON
 *    `null` / `0` / `""` / `false` is a legal included value — the discriminant
 *    is `omitted`, never value-nullness;
 *  - **metadata-only** (`omitted: true`): `value` is absent and `reason` (when
 *    present) says why. A server-omitted entry passes through with its wire
 *    `reason` (`"too_large"`); an included value that is **not valid JSON**
 *    degrades to this arm with the SDK-synthesized `reason: "not_json"` (never a
 *    wire value).
 *
 * `reason` is an **open vocabulary** — tolerate unknown values. Known values:
 * `"too_large"` (server) and `"not_json"` (SDK-side, `getBatchJSON` only).
 */
type BatchJSONEntry<T> = {
  readonly key: string;
  readonly crc32c: string;
  readonly contentType: string;
  readonly size: number;
} & (
  | { readonly omitted?: false; readonly value: T }
  | { readonly omitted: true; readonly value?: never; readonly reason?: string }
);

/** A {@link BatchJSONEntry} plus the record's owner uid — one `records.getBatchJSON` row. */
type RecordBatchJSONEntry<T> = BatchJSONEntry<T> & { readonly owner: string };

// ===========================================================================
// Capture-surface shapes (window.backlit.capture)
// ===========================================================================

/** {@link PutResult} plus the `"{prefix}-{guid}"` handle the object was stored under. */
interface CaptureCreateResult {
  /** The full `"{prefix}-{guid}"` handle. Pass it back verbatim to update/get/delete. */
  readonly handle: string;
  /** Base64-encoded Castagnoli CRC32C of the body. */
  readonly crc32c: string;
}

/** One entry of a `capture.list` response — handle + metadata, never the value. */
interface CaptureListEntry {
  /** The full `"{prefix}-{guid}"` handle. */
  readonly handle: string;
  /** Base64-encoded Castagnoli CRC32C of the body. */
  readonly crc32c: string;
  /** The stored content-type. */
  readonly contentType: string;
  /** The body's logical size in bytes. */
  readonly size: number;
}

// ===========================================================================
// Push-surface shapes (window.backlit.push)
// ===========================================================================

/** The OS notification-permission tri-state (mirrors `NotificationPermission`). */
type PushPermission = "granted" | "denied" | "default";

/**
 * Synchronous capability probe returned by {@link BacklitPush.supported} — an
 * honest report of whether this browser can subscribe to push right now.
 */
interface PushSupport {
  /** Can this browser subscribe to push at all, in this context, right now? */
  readonly supported: boolean;
  /**
   * When `supported` is `false`, a short tag for why: `"off_host"` (not a
   * deployed glow), `"insecure_context"`, `"no_service_worker"`,
   * `"no_push_manager"`, or `"requires_install"`. Omitted when `supported` is
   * `true`.
   */
  readonly reason?: string;
  /**
   * `true` on a platform where push works only from an installed home-screen app
   * and it isn't installed yet (iOS Safari). Implies `supported: false`.
   */
  readonly requiresInstall: boolean;
  /** Whether the page is running as an installed (standalone) app. */
  readonly installed: boolean;
}

/** Current client-side push state, from {@link BacklitPush.state}. */
interface PushState {
  /** The OS notification permission. */
  readonly permission: PushPermission;
  /** Whether this browser currently holds a push subscription. */
  readonly subscribed: boolean;
  /** The server-side subscription id when subscribed, else `""`. */
  readonly endpointId: string;
}

/** What {@link BacklitPush.subscribe} resolves to. */
interface SubscribeResult {
  /** The server-side subscription id for this browser's subscription. */
  readonly endpointId: string;
  /** Always `"granted"` (subscribe rejects with `permission_denied` otherwise). */
  readonly permission: "granted";
}

/** An event delivered to a {@link BacklitPush.watch} callback. */
type PushWatchEvent =
  /** The user tapped a delivered notification; `url` is its tap target. */
  | { readonly type: "notification-click"; readonly url: string }
  /** The browser rotated the subscription and the service worker re-registered it. */
  | { readonly type: "subscription-changed" }
  /** The OS notification permission changed; `permission` is the new value. */
  | { readonly type: "permission-changed"; readonly permission: PushPermission };

/** Callback registered with {@link BacklitPush.watch}. */
type PushWatchCallback = (event: PushWatchEvent) => void;

/** Returned by {@link BacklitPush.watch}. Idempotent — calling it twice is a no-op. */
type PushUnwatch = () => void;

/**
 * `window.backlit.push` — Web Push subscription management. The platform owns
 * the service worker (auto-registered on load); do **not** register your own on
 * a Backlit glow. Requires a signed-in user for subscribe/state/unsubscribe/test.
 */
interface BacklitPush {
  /**
   * Synchronous capability probe — the **only** sync, never-throwing SDK
   * method. Off a glow host it returns `{ supported:false,
   * requiresInstall:false, installed:false }` (it does **not** throw
   * `unsupported_host`). Gate your "Enable notifications" UI on `.supported`;
   * when `false`, `.reason` / `.requiresInstall` say why.
   */
  supported(): PushSupport;
  /**
   * Report client-side push state: the OS `permission`, whether this browser is
   * `subscribed`, and the server-side `endpointId` (or `""`). Throws
   * `unsupported` / `requires_install` when {@link BacklitPush.supported} is
   * `false`, and `unsupported_host` off a glow host.
   */
  state(): Promise<PushState>;
  /**
   * Subscribe the signed-in user's browser to push: request permission (throws
   * `permission_denied` if declined), register the platform service worker,
   * subscribe via the Push API, and report the subscription to Backlit. Throws
   * `unsupported` / `requires_install` (unsupported context), `unsupported_host`
   * (off a glow host), `unauthenticated` (no signed-in user), or the server push
   * codes.
   */
  subscribe(): Promise<SubscribeResult>;
  /**
   * Remove this browser's push subscription (browser + Backlit). A no-op when
   * there is no active subscription. Requires a signed-in user.
   */
  unsubscribe(): Promise<void>;
  /**
   * Send a test push to the signed-in user's own subscriptions. Requires a
   * signed-in user with at least one active subscription (throws `not_found`
   * if none).
   */
  test(): Promise<void>;
  /**
   * Register a callback for push client events — a notification tap
   * (`notification-click`, with the `url`), a service-worker subscription
   * rotation (`subscription-changed`), and OS permission changes
   * (`permission-changed`). Returns an idempotent unsubscribe; a no-op off a
   * glow host or in a non-browser context.
   */
  watch(callback: PushWatchCallback): PushUnwatch;
}

// ===========================================================================
// Realtime
// ===========================================================================

/**
 * Payload delivered to `backlit.on("storage.change", …)` handlers on every
 * successful `data` / `userdata` / `records` set or delete. (`capture` is
 * silent by design.)
 */
interface StorageChangeEvent {
  /** Which store the write hit. */
  readonly store: "data" | "userdata" | "records";
  /** `"set"` for put/CAS, `"delete"` for delete. */
  readonly operation: "set" | "delete";
  /** The key written or deleted. */
  readonly key: string;
  /** Base64-encoded Castagnoli CRC32C of the body; `""` on a delete event. */
  readonly crc32c: string;
  /** Records events only: the record's owner uid. Absent for data/userdata. */
  readonly owner?: string;
}

type StorageChangeHandler = (event: StorageChangeEvent) => void;

/** Returned by `on(...)`. Idempotent — calling it twice is a no-op. */
type Unsubscribe = () => void;

// ===========================================================================
// Errors
// ===========================================================================

/**
 * Every `code` {@link BacklitError} can carry. Matches the server's
 * `{error:{code,message}}` envelope verbatim, plus the SDK-side client codes.
 */
type BacklitErrorCode =
  // Preamble / transport (server-emitted)
  | "invalid_host"
  | "glow_not_found"
  | "glow_dark"
  | "region_mismatch"
  | "unauthenticated"
  | "cross_glow_token"
  | "forbidden"
  | "internal"
  // Data plane (server-emitted)
  | "not_found"
  | "invalid_key"
  | "invalid_prefix"
  | "invalid_cursor"
  | "invalid_handle"
  | "unknown_handle"
  | "payload_too_large"
  | "quota_exceeded"
  | "unsupported_content_type"
  | "invalid_body"
  | "method_not_allowed"
  // Emitted BOTH server- and client-side: `conflict` is the SDK's
  // updateJSON retry-exhaustion (status 0) AND the server's 412 when a
  // records delete/reassign loses a concurrent-write race; `invalid_argument`
  // is the SDK's pre-flight validation (status 0) AND the server's 400 for a
  // malformed `records.reassign` owner uid.
  | "conflict"
  | "invalid_argument"
  // Client-side only (SDK-emitted, status 0)
  | "network"
  | "unsupported_host"
  // Push-only client codes (SDK-emitted by window.backlit.push.*, status 0):
  // `unsupported` — this browser can't do push at all (no service worker /
  // PushManager / secure context); `requires_install` — push works only from an
  // installed home-screen app and it isn't installed yet (iOS Safari);
  // `permission_denied` — the user declined the notification-permission prompt.
  | "unsupported"
  | "requires_install"
  | "permission_denied"
  // Edge document-path codes — emitted while the edge serves the glow's
  // assets or runs the signin cookie-handoff. A data/userdata/records/capture
  // call sees these only in rare edge cases; they pass through the envelope
  // verbatim, so they are part of the observable union.
  | "asset_not_found"
  | "no_live_version"
  | "version_not_found"
  | "invalid_asset_path"
  | "invalid_glow_state"
  | "missing_handoff"
  | "handoff_expired"
  | "handoff_invalid"
  | "handoff_replay"
  | "handoff_unknown_nonce"
  | "handoff_glow_mismatch";

/**
 * The single error class every SDK method throws (except {@link
 * AuthNamespace.me}, which never throws). Discriminate on `.code`.
 * `instanceof BacklitError` is reliable across realms.
 */
declare class BacklitError extends Error {
  readonly code: BacklitErrorCode;
  /** HTTP status, or `0` for network / client-side validation failures. */
  readonly status: number;
  /** The underlying Error or fetch failure, when there is one. */
  readonly backlitCause: unknown;
  constructor(code: BacklitErrorCode, message: string, status?: number, cause?: unknown);
}

// ===========================================================================
// Namespaces
// ===========================================================================

/** `window.backlit.auth` — signed-in user identity. */
interface AuthNamespace {
  /**
   * The signed-in user, or `null` when there is none (Public glows, signed-out
   * visitors, the SDK loaded off a glow host, and network failures all resolve
   * `null`). **Never throws.**
   */
  me(): Promise<BacklitUser | null>;
  /**
   * One cursor-paginated page of the glow's user roster as a {@link ListPage}
   * of {@link BacklitUser} — `{ items, next }`, reusing the {@link ListOptions}
   * / {@link ListPage} types the `data` / `userdata` / `records` / `capture`
   * `list()` surfaces use. Pass `opts` (`{ cursor?, limit? }`) to page;
   * paginate by re-calling with the previous page's `next` until it is `""`.
   * **Admin only and read-only.** Unlike {@link AuthNamespace.me} this THROWS
   * {@link BacklitError}: `forbidden` (non-admin), `unauthenticated` (no
   * signed-in user), `invalid_cursor` (a malformed cursor), `unsupported_host`
   * (off a glow host), or `network`.
   */
  users(opts?: ListOptions): Promise<ListPage<BacklitUser>>;
  /**
   * Send the visitor to sign in (top-level navigation; returns `void`).
   * `returnPath` is an absolute same-origin path to land on afterwards
   * (default: the current page; anything else is sanitised to `/`). A silent
   * no-op off a deployed glow host. Useful for a "Sign in" button.
   */
  login(returnPath?: string): void;
  /**
   * Sign the visitor out and return them to `returnPath` (an absolute
   * same-origin path; default the current page). Top-level navigation, returns
   * `void`; a silent no-op off a deployed glow host.
   */
  logout(returnPath?: string): void;
}

// ===========================================================================
// Key & prefix constraint
// ===========================================================================
//
// Every `key` and `prefix` argument to `data.*`, `userdata.*`, and `records.*`
// — and the `prefix` argument to `capture.create` / `capture.list` — may use
// only the RFC 3986 §2.3 *unreserved* characters:
//
//     A–Z   a–z   0–9   -   .   _   ~
//
// and must be 1–256 bytes (a `prefix` may be empty, meaning "match everything
// in the silo"). Slashes and every other character are rejected. The rule is
// enforced both client-side — the SDK pre-flights it and throws
// `invalid_key` / `invalid_prefix` before any request — and server-side (the
// data API rejects with the same code). Capture *handles* are NOT keys: they
// keep the stricter `"{prefix}-{guid}"` form (see {@link CaptureNamespace}).

/**
 * The glow-shared key/value store (`window.backlit.data`). Readable by any
 * session with a valid glow session — every Public-glow visitor and every
 * signed-in user. **Writes require a signed-in user with write permission**:
 * anonymous sessions (every Public-glow visitor, and signed-out visitors on
 * an Accounts glow) get `unauthenticated`, and `viewer`-permission users get
 * `forbidden`, on `put`/`delete`/`putIfMatch` and the JSON write wrappers.
 * More than one user can write the same key, so prefer
 * {@link DataNamespace.updateJSON} / {@link DataNamespace.putIfMatch} over a
 * bare {@link DataNamespace.put} for shared mutable state. `key` arguments
 * are `[A-Za-z0-9._~-]` and must be 1–256 bytes.
 */
interface DataNamespace {
  /** Read the value at `key`. Throws `not_found` if it was never written. */
  get(key: string): Promise<BlobResult>;
  /**
   * Unconditional overwrite (last-writer-wins). `body` is `string | Blob |
   * ArrayBuffer | ArrayBufferView`; `contentType` is required and forwarded
   * verbatim. For shared mutable state prefer `updateJSON`/`putIfMatch`.
   */
  put(key: string, body: BodyInit, contentType: string): Promise<PutResult>;
  /**
   * Atomic compare-and-swap: write only if the current value's CRC equals
   * `expectedCrc32c` (empty string = create-only / expect-absent). A mismatch
   * resolves `{ matched: false, witness }` and never throws.
   */
  putIfMatch(key: string, body: BodyInit, contentType: string, expectedCrc32c: string): Promise<PutIfMatchResult>;
  /** Remove `key`. Throws `not_found` if absent (delete is not idempotent). */
  delete(key: string): Promise<void>;
  /**
   * List one bounded page of entries whose key starts with `prefix` (omit/`""`
   * lists everything), plus an opaque `next` cursor. Pass `opts.cursor` (a prior
   * page's `next`) to continue and `opts.limit` to size the page (clamped to
   * `[1,1000]`, default 500); paginate until `next` is `""`.
   */
  list(prefix?: string, opts?: ListOptions): Promise<ListPage<ListEntry>>;
  /**
   * The value-bearing sibling of {@link DataNamespace.list}: the same list-shaped
   * input and `{ items, next }` page, but each entry carries its `value` as a
   * {@link Blob}. An entry the server dropped at the per-response value budget
   * arrives metadata-only with `omitted: true` (narrow on it — see
   * {@link BatchEntry}). `opts.limit` is clamped to `[1,500]` (default 100);
   * paginate on `next` until `""`.
   */
  getBatch(prefix?: string, opts?: GetBatchOptions): Promise<ListPage<BatchEntry>>;

  /** `get` + `JSON.parse`. Throws `not_found` on a miss, `invalid_body` if not JSON. */
  getJSON<T = unknown>(key: string): Promise<JSONResult<T>>;
  /**
   * {@link DataNamespace.getBatch} with each included value `JSON.parse`d to `T`
   * client-side (content-type-agnostic, `getJSON` parity). A value that fails to
   * parse degrades that entry to the omitted arm with `reason: "not_json"`; a
   * server-omitted entry passes through with its wire `reason`. One `T` per page
   * (see {@link BatchJSONEntry}).
   */
  getBatchJSON<T = unknown>(prefix?: string, opts?: GetBatchOptions): Promise<ListPage<BatchJSONEntry<T>>>;
  /** `JSON.stringify(value)` + `put` as `application/json`. Throws `invalid_argument` if not serializable. */
  putJSON(key: string, value: unknown): Promise<PutResult>;
  /** JSON form of `putIfMatch` — the witness carries an already-parsed value. */
  putJSONIfMatch<T = unknown>(key: string, value: unknown, expectedCrc32c: string): Promise<PutJSONIfMatchResult<T>>;
  /**
   * The safe read-modify-write for shared JSON state: load → `mutate` →
   * compare-and-swap → rebase-and-retry. `mutate(current)` (current is
   * `undefined` on first write) MUST be replayable. Throws `conflict` if it
   * can't win within `maxAttempts` (default 6).
   */
  updateJSON<T = unknown>(key: string, mutate: (current: T | undefined) => T, options?: UpdateJSONOptions): Promise<JSONResult<T>>;
}

/**
 * The per-user data silo (`window.backlit.userdata`) — identical to {@link
 * DataNamespace} but each signed-in user has a private, isolated keyspace.
 * **Requires a signed-in user** (Private glows, or signed-in visitors on an
 * Accounts glow): every method throws `unauthenticated` on a Public glow or
 * for a signed-out visitor (no user session). `key` arguments are
 * `[A-Za-z0-9._~-]` and must be 1–256 bytes.
 */
interface UserDataNamespace {
  get(key: string): Promise<BlobResult>;
  put(key: string, body: BodyInit, contentType: string): Promise<PutResult>;
  putIfMatch(key: string, body: BodyInit, contentType: string, expectedCrc32c: string): Promise<PutIfMatchResult>;
  delete(key: string): Promise<void>;
  /** Like `data.list`: one bounded page + an opaque `next` cursor. */
  list(prefix?: string, opts?: ListOptions): Promise<ListPage<ListEntry>>;
  /** Like `data.getBatch`, scoped to this user's silo: value-bearing entries + `next`. */
  getBatch(prefix?: string, opts?: GetBatchOptions): Promise<ListPage<BatchEntry>>;
  getJSON<T = unknown>(key: string): Promise<JSONResult<T>>;
  /** Like `data.getBatchJSON`, scoped to this user's silo: JSON-parsed entries + `next`. */
  getBatchJSON<T = unknown>(prefix?: string, opts?: GetBatchOptions): Promise<ListPage<BatchJSONEntry<T>>>;
  putJSON(key: string, value: unknown): Promise<PutResult>;
  putJSONIfMatch<T = unknown>(key: string, value: unknown, expectedCrc32c: string): Promise<PutJSONIfMatchResult<T>>;
  updateJSON<T = unknown>(key: string, mutate: (current: T | undefined) => T, options?: UpdateJSONOptions): Promise<JSONResult<T>>;
}

/**
 * The public-read, owner-write store (`window.backlit.records`) — between
 * `data` (shared) and `userdata` (private). Any signed-in user creates records
 * and reads everyone's; only the record's creator (`owner`) or an `admin` may
 * overwrite/delete/reassign. **Requires a signed-in user** (`unauthenticated`
 * on a Public glow or for a signed-out visitor) and **free** (no
 * subscription). `get`/`list`/`putIfMatch`/`updateJSON` surface the `owner`
 * uid. `key` arguments are `[A-Za-z0-9._~-]` and must be 1–256 bytes.
 */
interface RecordsNamespace {
  get(key: string): Promise<RecordResult>;
  /** Create (first write claims it) or overwrite your own. A viewer CAN create. */
  put(key: string, body: BodyInit, contentType: string): Promise<PutResult>;
  putIfMatch(key: string, body: BodyInit, contentType: string, expectedCrc32c: string): Promise<RecordPutIfMatchResult>;
  delete(key: string): Promise<void>;
  /** Like `data.list` but each entry carries the record's `owner` uid; one bounded page + `next`. */
  list(prefix?: string, opts?: ListOptions): Promise<ListPage<RecordListEntry>>;
  /** Like `data.getBatch` but each value-bearing entry carries the record's `owner` uid. */
  getBatch(prefix?: string, opts?: GetBatchOptions): Promise<ListPage<RecordBatchEntry>>;
  getJSON<T = unknown>(key: string): Promise<RecordJSONResult<T>>;
  /** Like `data.getBatchJSON` but each entry carries the record's `owner` uid. */
  getBatchJSON<T = unknown>(prefix?: string, opts?: GetBatchOptions): Promise<ListPage<RecordBatchJSONEntry<T>>>;
  putJSON(key: string, value: unknown): Promise<PutResult>;
  putJSONIfMatch<T = unknown>(key: string, value: unknown, expectedCrc32c: string): Promise<RecordPutJSONIfMatchResult<T>>;
  updateJSON<T = unknown>(key: string, mutate: (current: T | undefined) => T, options?: UpdateJSONOptions): Promise<RecordJSONResult<T>>;
  /** **Admin only.** Move a record's owner to `newOwnerUid` (metadata-only). */
  reassign(key: string, newOwnerUid: string): Promise<void>;
}

/**
 * The write-only capture store (`window.backlit.capture`) for telemetry / form
 * submissions the app can capture but never read back. `create`/`update` are
 * open to any session (the handle is the capability); `get`/`list`/`delete`
 * are **admin only**. `prefix` arguments are `[A-Za-z0-9._~-]` and must be
 * 1–256 bytes.
 */
interface CaptureNamespace {
  /** Store a value; returns its `"{prefix}-{guid}"` handle. `prefix` is required. */
  create(prefix: string, body: BodyInit, contentType: string): Promise<CaptureCreateResult>;
  /** Replace the value at an existing handle. Open to any session. */
  update(handle: string, body: BodyInit, contentType: string): Promise<PutResult>;
  /** **Admin only.** Read the value at a handle. Throws `unknown_handle` on a miss. */
  get(handle: string): Promise<BlobResult>;
  /** **Admin only.** Enumerate handles (never values); `prefix` matches the handle. One bounded page + `next`. */
  list(prefix?: string, opts?: ListOptions): Promise<ListPage<CaptureListEntry>>;
  /** **Admin only.** Remove the object at a handle. Throws `unknown_handle` on a miss. */
  delete(handle: string): Promise<void>;
}

/** The `window.backlit` global the hosted bundle attaches. */
interface Backlit {
  /** The bundled SDK version, e.g. `"1.0.0"`. */
  readonly version: string;
  readonly auth: AuthNamespace;
  readonly data: DataNamespace;
  readonly userdata: UserDataNamespace;
  readonly records: RecordsNamespace;
  readonly capture: CaptureNamespace;
  /**
   * Web Push subscription management — `supported()` (the only sync,
   * never-throwing SDK method), `state()`, `subscribe()`, `unsubscribe()`,
   * `test()`, and `watch()`. The platform service worker is auto-registered on
   * load for every glow (universal install), independent of push.
   */
  readonly push: BacklitPush;
  /** The error class every method throws — for `instanceof` checks. */
  readonly BacklitError: typeof BacklitError;
  /**
   * Subscribe to runtime events. The only event in v1 is `"storage.change"`,
   * fired on every `data`/`userdata`/`records` set or delete on this glow.
   * Returns an unsubscribe function.
   */
  on(event: "storage.change", handler: StorageChangeHandler): Unsubscribe;
  /**
   * Remove the Backlit floating action button this SDK injects on load.
   * Honoured only on a paid plan (a free author's call is a silent no-op);
   * never throws, idempotent, and race-safe (works even if called before the
   * button has injected). Removing Backlit branding is a paid feature.
   */
  hideUI(): void;
  /**
   * Set to `true` once the page is serving code older than the glow's current
   * live version (apps that care can prompt a reload).
   * @internal Non-contractual: the leading underscore means it is NOT part of
   * the typed v1 surface and may change without notice.
   */
  readonly _versionStale?: boolean;
}

/** The global object attached by `<script src=".../sdk/v1/sdk.js">`. */
declare const backlit: Backlit;

interface Window {
  /**
   * The Backlit runtime SDK global. Attached wherever the bundle loads, but
   * functional only on a deployed glow host — off-host every data method
   * throws `unsupported_host` and `auth.me()` resolves `null`.
   */
  readonly backlit: Backlit;
}