@rebasepro/server 0.16.0 → 0.16.1-canary.g041c925

package/dist/storage/GCSStorageController.d.ts

@@ -5,7 +5,7 @@
  * optional peer dependency — users who don't need GCS never pay for the
  * import cost or need it installed.
  */
-import { StorageController, GCSStorageConfig } from "./types";
+import { StorageController, GCSStorageConfig } from "./types.js";
 import { UploadFileProps, UploadFileResult, DownloadConfig, StorageListResult } from "@rebasepro/types";
 /**
  * Google Cloud Storage implementation of `StorageController`.

package/dist/storage/LocalStorageController.d.ts

@@ -1,7 +1,7 @@
 /**
  * Local filesystem storage controller
  */
-import { StorageController, LocalStorageConfig } from "./types";
+import { StorageController, LocalStorageConfig } from "./types.js";
 import { UploadFileProps, UploadFileResult, DownloadConfig, StorageListResult } from "@rebasepro/types";
 /**
  * Bucket used when a call names none.

package/dist/storage/S3StorageController.d.ts

@@ -1,7 +1,7 @@
 /**
  * S3-compatible storage controller (works with AWS S3 and MinIO)
  */
-import { S3StorageConfig, StorageController } from "./types";
+import { S3StorageConfig, StorageController } from "./types.js";
 import { DownloadConfig, StorageListResult, UploadFileProps, UploadFileResult } from "@rebasepro/types";
 /**
  * S3-compatible storage implementation

package/dist/storage/cache-headers.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Cache and revalidation headers for served objects.
+ *
+ * ## Why every byte still goes through the process
+ *
+ * `routes.ts` deliberately proxies rather than redirecting to a signed URL —
+ * mixed content and unreachable VPC endpoints, both documented there. That
+ * decision stands. What it cost was caching: a proxied response only caches as
+ * well as its headers say, and the local path sent none at all, so every load
+ * of every image re-read the file and re-sent the body.
+ *
+ * This module is the headers. It does not change where bytes come from; it
+ * lets the client stop asking for them.
+ *
+ * ## Why `immutable` is wrong here, and was
+ *
+ * The remote path sent `public, max-age=3600, immutable`, and the transform
+ * paths sent it with `max-age=31536000`. `immutable` is a promise that the body
+ * at this URL will never change. A storage key can be overwritten — `putObject`
+ * on an existing key is an ordinary operation — so the promise is false for
+ * every object this server serves, and the symptom is an upload that replaces a
+ * file which then does not visibly change for an hour, or a year.
+ *
+ * Revalidation replaces it. With a validator the client asks "still this one?"
+ * and gets a 304 with no body, which costs a round trip instead of a transfer.
+ *
+ * ## Why `public` was a leak
+ *
+ * The same header said `public` for every object, including one that required
+ * authentication to fetch. `public` is explicit permission for a *shared* cache
+ * — a CDN, a corporate proxy — to store the response and serve it to somebody
+ * else. Private objects are now `private`, which is the directive that says a
+ * browser may keep it but a shared cache may not.
+ */
+import type { Context } from "hono";
+/**
+ * A weak validator built from size and modification time.
+ *
+ * Weak (`W/`) because it is not a digest of the body: two different bodies of
+ * the same length written in the same millisecond would collide. That is the
+ * same trade nginx makes for static files, and the alternative — hashing every
+ * object on every request — costs more than it saves for content this server is
+ * already streaming from somewhere else.
+ */
+export declare function buildEntityTag(size: number, lastModifiedMs: number): string;
+export interface ObjectValidators {
+    etag: string;
+    /** RFC 9110 date, second-resolution. */
+    lastModified: string;
+    lastModifiedMs: number;
+}
+export declare function objectValidators(size: number, lastModifiedMs: number): ObjectValidators;
+export interface CacheControlOptions {
+    /**
+     * Whether a *shared* cache may store this. True only for objects that need
+     * no credentials to fetch.
+     */
+    isPublic: boolean;
+    /**
+     * How long a client may reuse the response without asking. Short by
+     * default, because the object behind it is mutable.
+     */
+    maxAgeSeconds: number;
+    /**
+     * Public responses only: how long a stale copy may be served while a
+     * revalidation happens in the background. Shared caches honour it; it turns
+     * the revalidation round trip into something the user does not wait for.
+     */
+    staleWhileRevalidateSeconds?: number;
+}
+export declare function cacheControl(options: CacheControlOptions): string;
+/**
+ * Whether the request already holds this exact representation.
+ *
+ * `If-None-Match` wins outright when present: it is an exact validator, whereas
+ * `If-Modified-Since` has second resolution and is only consulted in its
+ * absence — again the order RFC 9110 requires.
+ */
+export declare function isNotModified(c: Context, validators: ObjectValidators): boolean;
+/**
+ * Put the validators and the cache policy on a response.
+ *
+ * Applied to the 304 as well as the 200: a 304 that omits them tells the client
+ * nothing about how long the answer holds, so the next load revalidates again
+ * immediately and the round trip repeats forever.
+ */
+export declare function applyCacheHeaders(c: Context, validators: ObjectValidators, options: CacheControlOptions): void;

package/dist/storage/index.d.ts

@@ -11,17 +11,17 @@
  * For other providers (Azure Blob, etc.), implement the
  * `StorageController` interface and pass the instance directly to the `storage` config.
  */
-export * from "./types";
-export { LocalStorageController } from "./LocalStorageController";
-export { S3StorageController } from "./S3StorageController";
-export { GCSStorageController } from "./GCSStorageController";
-export { createStorageRoutes } from "./routes";
-export type { StorageRoutesConfig } from "./routes";
-export * from "./storage-registry";
-export { parseTransformOptions, transformImage, isTransformableImage, TransformCache } from "./image-transform";
-export type { ImageTransformOptions } from "./image-transform";
-export { TusHandler } from "./tus-handler";
-import { BackendStorageConfig, StorageController } from "./types";
+export * from "./types.js";
+export { LocalStorageController } from "./LocalStorageController.js";
+export { S3StorageController } from "./S3StorageController.js";
+export { GCSStorageController } from "./GCSStorageController.js";
+export { createStorageRoutes } from "./routes.js";
+export type { StorageRoutesConfig } from "./routes.js";
+export * from "./storage-registry.js";
+export { parseTransformOptions, transformImage, isTransformableImage, TransformCache } from "./image-transform.js";
+export type { ImageTransformOptions } from "./image-transform.js";
+export { TusHandler } from "./tus-handler.js";
+import { BackendStorageConfig, StorageController } from "./types.js";
 /**
  * Create a storage controller from a config object.
  *

package/dist/storage/path-pattern.d.ts

@@ -0,0 +1,58 @@
+/**
+ * The storage key pattern language, in one place.
+ *
+ * `storagePolicies` invented it and `storageTriggers` needs exactly the same
+ * thing: match a key segment by segment, capture the named segments, and refuse
+ * a pattern that would silently do something other than it says. Two copies of
+ * a matcher used for access control is one copy too many — the day they drift
+ * is the day a policy and a trigger disagree about what `users/:uid/**` means,
+ * and only one of them is enforcing anything.
+ *
+ * The rules:
+ *
+ * - a literal segment matches itself
+ * - `*` matches exactly one segment
+ * - `:name` matches one segment and captures it
+ * - `**` matches the rest of the key, including nothing, and is only allowed as
+ *   the final segment
+ *
+ * Compilation is strict and happens at boot: a `**` in the middle, a `:` with
+ * no name, or the same capture twice are all errors, because each of them is a
+ * pattern whose author believed something the matcher does not do.
+ */
+/** A pattern that cannot be compiled. Thrown at boot, never per request. */
+export declare class StoragePatternError extends Error {
+    constructor(message: string);
+}
+export interface CompiledStoragePattern {
+    segments: string[];
+    /** True when the last segment is `**`. */
+    trailing: boolean;
+    /** The pattern as written, for error messages and logs. */
+    source: string;
+}
+/**
+ * Split a key into segments, dropping empty ones.
+ *
+ * Empty segments come from a leading slash or a `//`, and treating them as real
+ * would let `users//x` match a pattern expecting a captured segment with the
+ * empty string. Keys reaching here are already sanitized against traversal; this
+ * is about matching, not safety.
+ */
+export declare function segmentsOf(value: string): string[];
+/**
+ * Compile a pattern, or throw {@link StoragePatternError}.
+ *
+ * `label` names the thing being compiled in any error — `storagePolicies[2]`,
+ * `storageTriggers[0]` — so a boot failure points at the line to edit.
+ */
+export declare function compileStoragePattern(path: string, label: string): CompiledStoragePattern;
+/**
+ * Match a key against a compiled pattern.
+ *
+ * Returns the captured segments on a match — an empty object for a pattern that
+ * captures nothing — and `undefined` on a miss. The distinction matters: a
+ * pattern with no `:name` still matches, and `{}` is a match while `undefined`
+ * is not.
+ */
+export declare function matchStoragePattern(compiled: CompiledStoragePattern, key: string): Record<string, string> | undefined;

package/dist/storage/policies.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Declarative access control for storage.
+ *
+ * Storage is not under row-level security, so `storageAuthorize` — a hook, a
+ * piece of imperative code — was the whole access-control model. That is the one
+ * place the claim "security lives in the database" does not hold, and it shows
+ * in the shape of the alternative: without a hook, **any authenticated caller
+ * may read, overwrite, delete or list any key they can name**, because storage
+ * keys share one flat namespace.
+ *
+ * A policy list says the same things declaratively, and can be read without
+ * running it:
+ *
+ * ```ts
+ * storagePolicies: [
+ *     { path: "public/**", operations: ["read"], allow: "public" },
+ *     { path: "users/:uid/**", allow: ({ params, user }) => user?.uid === params.uid }
+ * ]
+ * ```
+ *
+ * ## Deny by default, and why that is the whole design
+ *
+ * A key matched by no policy is refused. That makes every widening an explicit,
+ * reviewable line, and it makes a mistake in this module fail *closed* — a
+ * pattern that fails to match denies access rather than granting it. Authz code
+ * that fails open is worth more to an attacker than the feature is to anyone
+ * else, so the bias is deliberate and absolute.
+ *
+ * ## The hook remains, as an escape hatch and not as a fallback
+ *
+ * Ownership frequently lives in a row rather than in a key, which no pattern can
+ * express. So when policies match nothing, an explicit `storageAuthorize` is
+ * consulted before the request is refused. Present, it can widen; absent, the
+ * answer is no. Policies never *narrow* what the hook allowed and the hook never
+ * overrides a policy denial — each can only say yes, which keeps "who allowed
+ * this?" answerable by reading either one alone.
+ */
+import type { StorageAuthorize, StorageAuthorizeContext, StorageOperation } from "@rebasepro/types";
+/** Everything a predicate is told, plus whatever the path captured. */
+export interface StoragePolicyContext extends StorageAuthorizeContext {
+    /** Segments captured by `:name` placeholders in the matched path. */
+    params: Record<string, string>;
+}
+export type StoragePolicyPredicate = (ctx: StoragePolicyContext) => boolean | Promise<boolean>;
+export interface StoragePolicy {
+    /**
+     * A key pattern, matched segment by segment against the sanitized key.
+     *
+     * - a literal segment matches itself
+     * - `*` matches exactly one segment
+     * - `:name` matches one segment and captures it
+     * - `**` matches the rest of the key, including nothing, and is only
+     *   allowed as the final segment
+     */
+    path: string;
+    /** Which operations this grants. Defaults to every one of them. */
+    operations?: StorageOperation[];
+    /**
+     * Who it grants to.
+     *
+     * - `"public"` — anyone, signed in or not
+     * - `"authenticated"` — any caller with a uid
+     * - a predicate — anything else, given the captured params and the user
+     */
+    allow: "public" | "authenticated" | StoragePolicyPredicate;
+}
+export declare class StoragePolicyError extends Error {
+    constructor(message: string);
+}
+/**
+ * Compile a policy list into a {@link StorageAuthorize}.
+ *
+ * Compiled once, at boot, so a malformed pattern fails the start rather than the
+ * first upload. `fallback` is an explicit `storageAuthorize`, consulted only
+ * when no policy matched.
+ */
+export declare function compileStoragePolicies(policies: StoragePolicy[], fallback?: StorageAuthorize): StorageAuthorize;
+/**
+ * The access-control function for a configuration, or `undefined` when it
+ * declares none.
+ *
+ * Kept separate from {@link compileStoragePolicies} so `init` has one call to
+ * make and one thing to reason about: policies, a hook, both, or neither.
+ */
+export declare function resolveStorageAccessControl(config: {
+    storagePolicies?: StoragePolicy[];
+    storageAuthorize?: StorageAuthorize;
+}): StorageAuthorize | undefined;

package/dist/storage/range.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Byte-range requests for served objects.
+ *
+ * Without `Accept-Ranges`, a browser will not offer to seek in an audio or
+ * video element served from here: it has no way to ask for the middle of a file,
+ * so scrubbing means fetching the whole thing from the start, and on a long
+ * recording it means fetching it again for every seek. Safari goes further and
+ * refuses to play a `<video>` at all unless the first response is a `206`.
+ *
+ * So this is not a performance nicety. For media it is the difference between a
+ * player that works and one that does not.
+ *
+ * ## What is implemented, and what is refused
+ *
+ * A single range — `bytes=0-499`, `bytes=500-`, `bytes=-500`. That is what every
+ * browser sends for media playback.
+ *
+ * Multiple ranges in one request (`bytes=0-99,200-299`) are **not** served.
+ * Answering them means composing a `multipart/byteranges` body, and nothing that
+ * matters sends them; a server may always answer a range request with the whole
+ * `200` instead, which is what happens here. Refusing to guess is better than a
+ * half-implemented multipart encoder.
+ *
+ * An unsatisfiable range — one starting past the end of the object — is a `416`
+ * with a `Content-Range: bytes /<size>`, as RFC 9110 requires. Answering `200`
+ * there would hand a player the whole file when it asked for a byte that does
+ * not exist, and it would never notice.
+ */
+/** A resolved, inclusive byte range within an object of known size. */
+export interface ByteRange {
+    start: number;
+    /** Inclusive, as the header is. */
+    end: number;
+    /** `end - start + 1`. */
+    length: number;
+}
+export type RangeParse = 
+/** No `Range` header, or one this server declines to honour. Serve `200`. */
+{
+    kind: "none";
+}
+/** Serve `206` with this range. */
+ | {
+    kind: "range";
+    range: ByteRange;
+}
+/** Serve `416`. The range cannot be satisfied for an object of this size. */
+ | {
+    kind: "unsatisfiable";
+};
+/**
+ * Parse a `Range` header against an object of `size` bytes.
+ *
+ * Deliberately conservative: anything malformed, multi-range, or in a unit other
+ * than bytes resolves to `none`, which serves the whole object. A range request
+ * answered with `200` is always legal; a range answered wrongly is a corrupted
+ * download.
+ */
+export declare function parseRange(header: string | undefined, size: number): RangeParse;
+/** The `Content-Range` for a served range. */
+export declare function contentRange(range: ByteRange, size: number): string;
+/** The `Content-Range` for a `416`, which names the size and no range. */
+export declare function unsatisfiableContentRange(size: number): string;

package/dist/storage/rendition-cache.d.ts

@@ -0,0 +1,45 @@
+import type { StorageController } from "./types.js";
+/**
+ * Where renditions live inside the source bucket.
+ *
+ * Fixed rather than configurable: it is the target of a lifecycle rule and of
+ * the route-layer refusal below, and both of those are worth being able to
+ * write down once, in the documentation, for every deployment.
+ */
+export declare const RENDITION_PREFIX = "_rebase/renditions/";
+/** True for a key that names the reserved rendition space. */
+export declare function isRenditionKey(key: string): boolean;
+export interface RenditionCacheConfig {
+    /** Off unless set. See the module comment for why. */
+    enabled?: boolean;
+}
+export interface DurableRendition {
+    data: Buffer;
+    contentType: string;
+}
+export interface DurableRenditionCache {
+    /** The stored rendition for this cache key, or null. Never throws. */
+    get(controller: StorageController, cacheKey: string, bucket: string | undefined): Promise<DurableRendition | null>;
+    /** Store a rendition. Never throws: a failed write is a slower cache. */
+    put(controller: StorageController, cacheKey: string, bucket: string | undefined, rendition: DurableRendition): Promise<void>;
+}
+/**
+ * The object key for a rendition.
+ *
+ * Hashed rather than derived from the source path: the source key can be up to
+ * 1024 characters and the transform options are a JSON object, so a readable
+ * composition would exceed key limits on exactly the paths people use — deep
+ * per-user prefixes. The source key is kept in the object's metadata, where it
+ * is available to anyone auditing the prefix and to nothing on the hot path.
+ */
+export declare function renditionKey(cacheKey: string, contentType: string): string;
+/**
+ * A rendition's key when reading, where the content type is not yet known.
+ *
+ * Reads try the known extensions rather than storing an index: four `getObject`
+ * calls at worst is still one round trip in the common case — the first
+ * candidate is the format the request asked for — and an index is a second
+ * thing to keep consistent with the objects it describes.
+ */
+export declare function renditionKeyCandidates(cacheKey: string, preferred?: string): string[];
+export declare function createDurableRenditionCache(): DurableRenditionCache;

package/dist/storage/routes.d.ts

@@ -7,10 +7,12 @@
  * is used.
  */
 import { Hono } from "hono";
-import { StorageController, type StorageAuthorize, type StorageAuthorizeData } from "./types";
-import { type StorageRegistry } from "./storage-registry";
+import { StorageController, type StorageAuthorize, type StorageAuthorizeData } from "./types.js";
+import { type StorageRegistry } from "./storage-registry.js";
 import { type StorageSourceDefinition, type AuthAdapter } from "@rebasepro/types";
-import { HonoEnv } from "../api/types";
+import { HonoEnv } from "../api/types.js";
+import { type StorageTrigger } from "./triggers.js";
+import { type RenditionCacheConfig } from "./rendition-cache.js";
 /**
  * Decide what to actually serve for a stored content type.
  *
@@ -24,8 +26,8 @@ export declare function resolveServedContentType(storedContentType: string): {
 };
 export interface StorageRoutesConfig {
     /**
-     * Single storage controller (backward-compatible).
-     * Used as fallback when no `registry` is provided.
+     * A single storage controller, for a backend with one storage source.
+     * Used when no `registry` is provided.
      */
     controller?: StorageController;
     /**
@@ -71,6 +73,16 @@ export interface StorageRoutesConfig {
      * resolved.
      */
     authorizeData?: () => StorageAuthorizeData | undefined;
+    /**
+     * Keep derived image renditions in the storage source instead of only in
+     * this process's memory. Off unless enabled — see `rendition-cache.ts` for
+     * why a read that writes to somebody's bucket is not a default.
+     */
+    renditionCache?: RenditionCacheConfig;
+    /**
+     * Run something when an object lands, or when one goes. See `triggers.ts`.
+     */
+    triggers?: StorageTrigger[];
 }
 /**
  * Extract the wildcard portion of a route path from the full request path.

package/dist/storage/storage-registry.d.ts

@@ -10,7 +10,7 @@
  * - String properties use `storageId` in their config to specify which storage to use
  * - Properties without `storageId` fallback to "(default)"
  */
-import { StorageController } from "./types";
+import { StorageController } from "./types.js";
 /**
  * The default storage identifier used when:
  * - A single storage controller is provided (not a map)

package/dist/storage/triggers.d.ts

@@ -0,0 +1,66 @@
+/** What happened to the object. */
+export type StorageTriggerEvent = "finalize" | "delete";
+export interface StorageEventContext {
+    /** Which event this is. */
+    event: StorageTriggerEvent;
+    /** The canonical storage key, as written. */
+    key: string;
+    /** The bucket, when the request named one. */
+    bucket?: string;
+    /** The storage source the object lives in. */
+    storageId: string;
+    /** Size in bytes. Present on `finalize`, absent on `delete`. */
+    size?: number;
+    /** The uploader's declared content type, when there was one. */
+    contentType?: string;
+    /** Segments captured by `:name` placeholders in the matched path. */
+    params: Record<string, string>;
+    /** Who made the request, when it was authenticated. */
+    user?: {
+        uid: string;
+        email?: string;
+        roles?: string[];
+    } | null;
+    /** When the event was raised, ISO 8601. */
+    at: string;
+}
+export type StorageTriggerHandler = (ctx: StorageEventContext) => void | Promise<void>;
+export interface StorageTrigger {
+    /**
+     * A key pattern, matched segment by segment against the canonical key.
+     *
+     * - a literal segment matches itself
+     * - `*` matches exactly one segment
+     * - `:name` matches one segment and captures it
+     * - `**` matches the rest of the key, including nothing, and is only
+     *   allowed as the final segment
+     */
+    path: string;
+    /** Which events fire it. Defaults to `["finalize"]`. */
+    events?: StorageTriggerEvent[];
+    /** A name for the logs. Defaults to the pattern. */
+    name?: string;
+    handler: StorageTriggerHandler;
+}
+/**
+ * A request's principal, in the shape a trigger is documented to receive.
+ *
+ * Hono's `user` variable is typed `AuthResult`, which admits `true` — some
+ * middleware sets a bare boolean to mean "authenticated, with no identity
+ * attached". A trigger asking "who did this?" is better told `null` than
+ * `true`, and better told `null` than a `{}` with no `uid`.
+ */
+export declare function triggerUser(raw: unknown): StorageEventContext["user"];
+export declare class StorageTriggerError extends Error {
+    constructor(message: string);
+}
+/** Fires the triggers a key and event match. Never throws. */
+export type StorageTriggerDispatcher = (ctx: Omit<StorageEventContext, "params">) => Promise<void>;
+/**
+ * Compile a trigger list into a dispatcher, or throw
+ * {@link StorageTriggerError}.
+ *
+ * Compiled at boot so a malformed pattern fails the start rather than the first
+ * upload — and, worse, rather than failing *silently* by matching nothing.
+ */
+export declare function compileStorageTriggers(triggers: StorageTrigger[]): StorageTriggerDispatcher;

package/dist/storage/tus-handler.d.ts

@@ -8,8 +8,8 @@
  * @see https://tus.io/protocols/resumable-upload
  */
 import type { Context } from "hono";
-import type { StorageController } from "./types";
-import { type StorageRegistry } from "./storage-registry";
+import type { StorageController } from "./types.js";
+import { type StorageRegistry } from "./storage-registry.js";
 /**
  * TUS resumable upload handler.
  *
@@ -33,6 +33,16 @@ export declare class TusHandler {
      * can only answer for the destination it is told about.
      */
     private authorizeUpload?;
+    /**
+     * Called once the bytes are stored, so storage triggers fire for the
+     * resumable path too. A trigger wired only to `POST /upload` would miss
+     * exactly the uploads big enough to be worth reacting to.
+     *
+     * Never throws: the dispatcher swallows handler errors, because the
+     * object is already written and failing here would tell the client to
+     * repeat a write that succeeded.
+     */
+    private onFinalized?;
     private uploads;
     private tusDir;
     private cleanupTimer?;
@@ -49,7 +59,28 @@ export declare class TusHandler {
      * Every routing value the write will use is passed in, because the hook
      * can only answer for the destination it is told about.
      */
-    authorizeUpload?: ((c: Context, key: string, bucket: string, storageId?: string) => Promise<void>) | undefined);
+    authorizeUpload?: ((c: Context, key: string, bucket: string, storageId?: string) => Promise<void>) | undefined, 
+    /**
+     * Called once the bytes are stored, so storage triggers fire for the
+     * resumable path too. A trigger wired only to `POST /upload` would miss
+     * exactly the uploads big enough to be worth reacting to.
+     *
+     * Never throws: the dispatcher swallows handler errors, because the
+     * object is already written and failing here would tell the client to
+     * repeat a write that succeeded.
+     */
+    onFinalized?: ((event: {
+        key: string;
+        bucket?: string;
+        storageId?: string;
+        size: number;
+        contentType?: string;
+        user?: {
+            uid: string;
+            email?: string;
+            roles?: string[];
+        } | null;
+    }) => Promise<void>) | undefined);
     /** Ensure the temp directory exists. */
     private ensureDir;
     /** Start periodic cleanup of stale uploads. */

package/dist/topics/runtime.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Topics, on the durable job queue.
+ *
+ * ## Why fan out at publish time
+ *
+ * Publishing writes **one job row per subscription**, not one row for the
+ * event. That is the shape SNS→SQS has and the reason is the same: each
+ * subscriber then retries on its own schedule, and a subscription that is
+ * broken or slow neither blocks the others nor causes them to run again. A
+ * single row per event forces one retry policy across every consumer, so the
+ * fourth attempt of a failing audit log re-delivers a welcome email that
+ * already went out.
+ *
+ * It also makes "did this subscriber get it" a row somebody can look at, which
+ * is the property the job queue was built for: work that gives up is *kept*,
+ * because a queue that silently drops what it could not deliver is
+ * indistinguishable from one with nothing to do.
+ *
+ * ## What at-least-once means here
+ *
+ * A handler can see the same event twice — a worker that dies holding a job
+ * releases it after the visibility timeout, and the next worker starts the
+ * handler again from the top. Handlers must tolerate that. It is the honest
+ * name for what a retrying queue does, which is why `at-most-once` is refused
+ * at declaration rather than quietly given the other guarantee.
+ *
+ * ## Transactional publish
+ *
+ * `enqueue` is a row insert, so a publish inside a transaction that rolls back
+ * was never published — the difference between "email sent for an order that
+ * does not exist" and nothing having happened at all.
+ */
+import { type ResourceDeclaration, type TopicRuntime } from "@rebasepro/types";
+import type { JobHandler, JobQueueClient } from "./../jobs/types.js";
+/** The job task name a subscription's deliveries are recorded under. */
+export declare function topicTaskName(topic: string, subscription: string): string;
+/** Attempts a subscription gets before its delivery is left failed. */
+export declare const DEFAULT_TOPIC_ATTEMPTS = 5;
+/**
+ * Build the job handlers every declared subscription needs.
+ *
+ * Returned rather than registered, because the queue takes its whole task map
+ * at construction — and a task map assembled in one place is one somebody can
+ * print.
+ */
+export declare function topicJobHandlers(): Record<string, JobHandler<never>>;
+export interface TopicRuntimeOptions {
+    queue: JobQueueClient;
+    /** Declared topics, so publishing to an undeclared one can be refused. */
+    topics: ResourceDeclaration[];
+}
+/**
+ * Build the runtime topics publish through.
+ *
+ * Publishing to a topic nothing declared throws. The handle API makes it hard
+ * to reach, but a string name from an ejected project or a dynamic caller can —
+ * and enqueueing under a task no worker handles would write rows nobody ever
+ * runs.
+ */
+export declare function createTopicRuntime(options: TopicRuntimeOptions): TopicRuntime;
+/**
+ * Install the runtime, and hand back a teardown.
+ *
+ * Publishing without one throws rather than resolving — an event that
+ * disappears into a resolved promise is the failure a queue exists to
+ * prevent — so it is installed for exactly as long as a backend is up.
+ */
+export declare function installTopicRuntime(options: TopicRuntimeOptions): () => void;

package/dist/{types-DSnOC4mF.js → types-BfKcm9do.js}

@@ -1,6 +1,7 @@
-import { createRequire as __createRequire } from "module";
-import "process";
-__createRequire(import.meta.url);
+import { createRequire as __rebaseCreateRequire } from "module";
+import __rebaseProcess from "process";
+globalThis.process ??= __rebaseProcess;
+__rebaseCreateRequire(import.meta.url);
 //#region src/storage/types.ts
 /**
 * Default maximum file size (50MB)
@@ -35,4 +36,4 @@ var DOCUMENT_MIME_TYPES = [
 //#endregion
 export { DOCUMENT_MIME_TYPES as n, IMAGE_MIME_TYPES as r, DEFAULT_MAX_FILE_SIZE as t };
 
-//# sourceMappingURL=types-DSnOC4mF.js.map
+//# sourceMappingURL=types-BfKcm9do.js.map