1// Wire types shared by the CLI and the Worker.2// This package must stay runtime-agnostic: Web APIs only, no Deno.* or Workers globals.34/**5 * Canonical metadata for one file in a manifest.6 *7 * The short property names are part of the version 1 wire format and are8 * hashed verbatim when deriving the manifest identity.9 */10export interface ManifestFile {11 /** Lowercase, 64-character SHA-256 digest of the exact file bytes. */12 h: string;13 /** Non-negative file size in bytes. */14 s: number;15 /** Media type stored and served for the file, resolved by the CLI at push time. */16 ct: string;17}1819/** Complete, versioned file map whose canonical bytes identify one site revision. */20export interface Manifest {21 /** Manifest schema version. Version `1` is the only supported value. */22 v: 1;23 /**24 * Map from validated relative paths to file metadata.25 *26 * Paths use forward slashes and omit a leading slash or `./`.27 */28 files: Record<string, ManifestFile>;29}3031/**32 * Destination for a push, expressed as either an exact numeric address or a33 * registered vault with an optional alias.34 */35export type Target =36 | {37 /** Numeric site address in the inclusive range `0x0000`–`0xffff`. */38 address: number;39 }40 | {41 /** Registered vault name that owns the destination address. */42 vault: string;43 /** Optional site alias within the vault; `null` requests an unaliased site. */44 alias?: string | null;45 };4647/** Supported site lifetimes. A number is a lifetime in days. */48export type Ttl = number | "forever";4950/** Why a commit received its resolved lifetime. */51export type TtlSource = "explicit" | "existing-site" | "vault" | "global";5253/** Lifecycle intent used to select a default vault. */54export type VaultLifecycle = "temporary" | "permanent";5556/** Server-owned default vault names for each lifecycle intent. */57export interface DefaultVaults {58 /** Vault selected for ordinary, finite-lifetime sharing. */59 temporary: string | null;60 /** Vault selected for durable application origins. */61 permanent: string | null;62}6364/** Body of `POST /api/push/prepare`: the manifest the client wants to push. */65export interface PrepareRequest {66 /** Complete manifest whose referenced blob availability should be checked. */67 manifest: Manifest;68}6970/** Reply from `POST /api/push/prepare` describing the content still required. */71export interface PrepareResponse {72 /** Lowercase SHA-256 of the canonical manifest bytes. */73 manifestHash: string;74 /** Lowercase SHA-256 blob digests that must be uploaded before committing. */75 missing: string[];76}7778/** Body of `POST /api/push/commit`: atomically publish content and its access policy. */79export interface CommitRequest {80 /** Complete manifest to publish as the site's current version. */81 manifest: Manifest;82 /** Address or vault destination that should receive the new version. */83 target: Target;84 /** Lifetime in days, `"forever"` for no expiry, or omitted to preserve an existing value (14 days for a new site). */85 ttl?: Ttl;86 /** Password to set, `null` to clear it, or omitted to preserve an existing value. */87 password?: string | null;88 /** App-only response policy recorded when deploying to a reserved app origin. */89 app?: {90 /** Content-Security-Policy emitted by the lofi build, if present. */91 contentSecurityPolicy?: string;92 };93}9495/** Reply from `POST /api/push/commit` identifying the published site revision. */96export interface CommitResponse {97 /** Four-character lowercase hexadecimal address, such as `"2a3f"`. */98 address: string;99 /** Absolute public URL on the site's isolated hostname. */100 url: string;101 /** Resolved site alias, or `null` for an unaliased address. */102 alias: string | null;103 /** Lowercase SHA-256 of the committed canonical manifest. */104 manifestHash: string;105 /** Unix expiry timestamp in seconds, or `null` for a permanent site. */106 expiresAt: number | null;107 /** Resolved lifetime in days, `"forever"`, or zero when an existing site is already expired. */108 ttl: Ttl;109 /** Policy layer that supplied the resolved lifetime. */110 ttlSource: TtlSource;111 /** Whether visitors must unlock the committed site with a password. */112 protected: boolean;113 /** Monotonically increasing push sequence number within this site. */114 seq: number;115}116117/** Owner-visible summary of one site, as returned by list and status endpoints. */118export interface SiteInfo {119 /** Four-character lowercase hexadecimal site address. */120 address: string;121 /** Name of the vault containing the site. */122 vault: string;123 /** Site alias within its vault, or `null` when unaliased. */124 alias: string | null;125 /** Lowercase SHA-256 of the site's current canonical manifest. */126 manifestHash: string;127 /** Unix timestamp, in seconds, when the site was created. */128 createdAt: number;129 /** Unix timestamp, in seconds, of the most recent site update. */130 updatedAt: number;131 /** Unix expiry timestamp in seconds, or `null` for a permanent site. */132 expiresAt: number | null;133 /** Absolute public URL of the site. */134 url: string;135 /** Whether visitors must unlock the site with a password. */136 protected: boolean;137}138139/** One entry in a site's push history. */140export interface PushInfo {141 /** Monotonically increasing push sequence number within the site. */142 seq: number;143 /** Lowercase SHA-256 of the manifest published by this push. */144 manifestHash: string;145 /** Unix timestamp, in seconds, when the push was committed. */146 pushedAt: number;147 /** Optional audit note, such as the source sequence of a revert. */148 note: string | null;149}150151/** A site plus its retained push history (powers `nzip site revert`). */152export interface SiteDetail extends SiteInfo {153 /** Retained push history ordered from newest to oldest. */154 history: PushInfo[];155}156157/**158 * Current manifest for a site, returned only by the authenticated recovery159 * API and used to locate and verify the bundle's blobs.160 */161export interface SourceResponse {162 /** Four-character lowercase hexadecimal address of the recovered site. */163 address: string;164 /** Lowercase SHA-256 of the returned canonical manifest. */165 manifestHash: string;166 /** Current manifest used to reconstruct and verify the hosted bundle. */167 manifest: Manifest;168}169170/** Owner-visible metadata and live site count for a registered vault. */171export interface VaultInfo {172 /** Numeric vault slot in the inclusive range `0x0`–`0xf`. */173 slot: number;174 /** Registered lowercase vault name. */175 name: string;176 /** Optional context describing the vault's intended audience or purpose. */177 description: string | null;178 /** Unix timestamp, in seconds, when the vault was registered. */179 createdAt: number;180 /** Number of currently live sites assigned to this vault. */181 siteCount: number;182 /** Vault-specific lifetime, or `null` to inherit the global fallback. */183 defaultTtl: Ttl | null;184 /** Lifetime new sites receive after applying the global fallback. */185 effectiveDefaultTtl: Ttl;186 /** Lifecycle intents for which this vault is the server default. */187 defaultFor: VaultLifecycle[];188}189190/** Reply to `GET /api/status`: server version and a snapshot of vaults and sites. */191export interface StatusResponse {192 /** Literal success marker for a healthy authenticated status response. */193 ok: true;194 /** Semantic version reported by the running nzip Worker. */195 version: string;196 /** Server-owned default vault names, selected by lifecycle intent. */197 defaultVaults: DefaultVaults;198 /** Fallback lifetime in days when a vault does not define one. */199 globalDefaultTtl: number;200 /** All registered vaults and their current site counts. */201 vaults: VaultInfo[];202 /** Total number of currently registered sites across every vault. */203 siteCount: number;204 /** Number of sites whose expiry falls within the next 48 hours. */205 expiringSoon: number;206}207208/** Body of a revert request: the push sequence number to repoint to (defaults to previous). */209export interface RevertRequest {210 /** Push sequence to restore; omission selects the newest differing version. */211 toSeq?: number;212}213214/** Body of a site PATCH. Omitted access-policy fields remain unchanged. */215export interface PatchSiteRequest {216 /** New lifetime in days, or `"forever"`; omission preserves the current expiry. */217 ttl?: Ttl;218 /** Password to set, `null` to clear it, or omitted to leave it unchanged. */219 password?: string | null;220}221222/** Body of `POST /api/apps`: reserve a permanent browser origin before deployment. */223export interface AppInitRequest {224 /** Named app destination. App reservations require an alias. */225 target: { vault: string; alias: string };226}227228/** Stable app-origin reservation returned by the management API. */229export interface AppReservationInfo {230 /** Four-character lowercase hexadecimal address. */231 address: string;232 /** Vault that owns the reservation. */233 vault: string;234 /** Alias permanently associated with this reservation. */235 alias: string;236 /** Absolute app URL on its isolated hostname. */237 url: string;238 /** Unix timestamp when this origin was first reserved. */239 createdAt: number;240 /** Whether site content currently exists at the reserved origin. */241 deployed: boolean;242}243244/** Standard error envelope returned by the API on failure. */245export interface ApiError {246 /** Human-readable error message safe to show to the authenticated client. */247 error: string;248}249250/** Body of `POST /api/notify`: a small, user-visible Web Push event. */251export interface NotifyRequest {252 /** Notification title. The Worker defaults this to `nzip` when omitted. */253 title?: string;254 /** Required notification body. */255 body: string;256 /**257 * Optional normalized, same-origin site path opened when the notification is258 * tapped. A site target is pinned to its current manifest when accepted and259 * will not open if that site changes before the tap.260 */261 path?: string;262 /** Optional provider-independent tag used to replace a related notification. */263 tag?: string;264}265266/**267 * Reply from `POST /api/notify` after durable outbox acceptance.268 *269 * Acceptance confirms that eligible deliveries were queued; it does not imply270 * that a push provider or device displayed the notification.271 */272export interface NotifyResponse {273 /** Stable identifier for the persisted notification event. */274 eventId: string;275 /** Number of active device deliveries placed in the outbox. */276 queuedDevices: number;277 /** Number of approved but inactive devices excluded from delivery. */278 inactiveDevices: number;279}280281/**282 * Current owner-controlled window during which new notification devices may283 * request enrollment. An opened window closes automatically after ten minutes.284 */285export interface NotifyPairingWindow {286 /** Whether the Worker currently accepts new enrollment requests. */287 enabled: boolean;288 /** Unix timestamp, in seconds, when pairing closes, or `null` while closed. */289 expiresAt: number | null;290}291292/**293 * Server-side lifecycle state for a notification device.294 *295 * Devices progress from `pending` enrollment to `approved`, then `active` once296 * a subscription is attached. `disabled`, `revoked`, and `expired` are297 * non-deliverable states.298 */299export type NotifyDeviceStatus =300 | "pending"301 | "approved"302 | "active"303 | "disabled"304 | "revoked"305 | "expired";306307/** Owner-visible notification device metadata. Subscription secrets are never returned. */308export interface NotifyDeviceInfo {309 /** Opaque, stable identifier used for owner actions such as revocation. */310 id: string;311 /** Owner-assigned display name, or `null` while pairing is pending. */312 name: string | null;313 /** Current enrollment and subscription lifecycle state. */314 status: NotifyDeviceStatus;315 /** Bounded browser and operating-system summary captured at enrollment. */316 userAgentSummary: string | null;317 /** Coarse device class such as phone, tablet, or desktop. */318 deviceClass: string | null;319 /** Two-letter ISO 3166-1 country code reported by the edge, when available. */320 country: string | null;321 /** Bounded region code reported by the edge, when available. */322 region: string | null;323 /** Network autonomous-system number reported by the edge, when available. */324 asn: number | null;325 /** Unix timestamp, in seconds, when enrollment began. */326 createdAt: number;327 /** Unix expiry timestamp for an unapproved pairing code, or `null` once inapplicable. */328 pairingExpiresAt: number | null;329 /** Unix expiry timestamp for an approved claim, or `null` when inapplicable. */330 claimExpiresAt: number | null;331 /** Unix timestamp, in seconds, of owner approval, or `null` before approval. */332 approvedAt: number | null;333 /** Unix timestamp, in seconds, of first subscription attachment, or `null` before it. */334 activeAt: number | null;335 /** Unix timestamp, in seconds, of the latest attachment, or `null` if never attached. */336 lastAttachedAt: number | null;337 /** Unix timestamp, in seconds, of the latest validated request, or `null` if unseen. */338 lastSeenAt: number | null;339 /** Unix timestamp, in seconds, of the latest successful delivery, or `null` if none. */340 lastSuccessAt: number | null;341 /** Bounded error class only; provider responses and subscription material are excluded. */342 lastError: string | null;343}344345/** Bounded context shown before the owner approves a pairing code. */346export interface NotifyApprovalPreview {347 /** Unix timestamp, in seconds, when enrollment began. */348 createdAt: number;349 /** Bounded browser and operating-system summary captured at enrollment. */350 userAgentSummary: string | null;351 /** Coarse device class such as phone, tablet, or desktop. */352 deviceClass: string | null;353 /** Two-letter ISO 3166-1 country code reported by the edge, when available. */354 country: string | null;355 /** Bounded region code reported by the edge, when available. */356 region: string | null;357 /** Network autonomous-system number reported by the edge, when available. */358 asn: number | null;359}360361/** Body of `POST /api/notify/approvals`. */362export interface NotifyApprovalRequest {363 /** Display-safe pairing code shown on the enrolling device. */364 code: string;365 /** Owner-assigned device name. */366 name: string;367}