@vllnt/convex-idempotency 0.1.0-canary.6abc175

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 bntvllnt
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,127 @@
+<!-- Badges -->
+[![convex-component](https://img.shields.io/badge/convex-component-EE342F.svg)](https://www.convex.dev/components)
+[![npm](https://img.shields.io/npm/v/@vllnt/convex-idempotency.svg)](https://www.npmjs.com/package/@vllnt/convex-idempotency)
+[![CI](https://github.com/vllnt/convex-idempotency/actions/workflows/ci.yml/badge.svg)](https://github.com/vllnt/convex-idempotency/actions/workflows/ci.yml)
+[![license](https://img.shields.io/npm/l/@vllnt/convex-idempotency.svg)](./LICENSE)
+
+# @vllnt/convex-idempotency
+
+Exactly-once idempotency key ledger for retried operations, as a Convex component.
+
+```ts
+const idem = new Idempotency(components.idempotency);
+const claim = await idem.begin(ctx, requestId);   // mints a claim, or short-circuits a replay
+if (claim.state === "done") return claim.result;  // replayed — skip the work
+// ... run the work ...
+await idem.complete(ctx, requestId, result);      // record the outcome for next time
+```
+
+Record an idempotency `key` with a grace TTL; on a replay short-circuit and return the prior outcome
+instead of re-running the work. Domain-neutral: payment intents, webhook deliveries, queue consumers,
+double-submit guards — any operation that must run **at most once** per key.
+
+## Features
+
+- **Exactly-once** per `(scope, key)` — `begin` mints an inflight claim that rides the mutation transaction; a concurrent retry sees `inflight` with a `retryAfterMs` backoff hint.
+- **Replay** — once `complete` records an outcome, a later `begin` returns `{ state: "done", result }` for a short-circuit.
+- **Split TTLs** — a short **inflight lease** (default 60s) so a crashed worker's claim self-heals, and a longer **done grace** (default 24h) after which a key may be re-minted.
+- **Lost-claim detection** — `complete` returns `{ recorded: true } | { recorded: false, reason }` so a host knows when its work finished but the row was gone. Opt into `upsertOnMissing`.
+- **Server-sourced time** — expiry is read from the server clock; a caller can't supply `now`, so an adversarial clock can't force a key to look live or expired.
+- **TTL validation** — non-positive or infinite TTLs throw `INVALID_TTL` before any write.
+- **Typed result** — `Idempotency<TResult>` types the stored outcome; a `resultValidator` narrows it at the boundary.
+- **Scopes** — global by default, or namespace per tenant / operation type.
+- **Bounded purge + cron** — a daily cron sweeps expired keys in batches and self-reschedules until clean.
+
+## Installation
+
+```bash
+pnpm add @vllnt/convex-idempotency
+```
+
+Peer dependency: `convex@^1.41.0`.
+
+## Usage
+
+```ts
+// convex/convex.config.ts
+import { defineApp } from "convex/server";
+import idempotency from "@vllnt/convex-idempotency/convex.config";
+
+const app = defineApp();
+app.use(idempotency);
+export default app;
+```
+
+```ts
+// convex/charge.ts — host owns auth; pass an opaque idempotency key in.
+import { components } from "./_generated/api";
+import { mutation } from "./_generated/server";
+import { v } from "convex/values";
+import { Idempotency } from "@vllnt/convex-idempotency";
+
+const idem = new Idempotency<{ chargeId: string }>(components.idempotency, {
+  resultValidator: v.object({ chargeId: v.string() }).parse, // narrow at the boundary
+});
+
+export const charge = mutation({
+  args: { requestId: v.string(), amount: v.number() },
+  handler: async (ctx, { requestId, amount }) => {
+    const claim = await idem.begin(ctx, requestId);
+    if (claim.state === "done") return claim.result;          // typed replay
+    if (claim.state === "inflight")
+      throw new Error(`retry in ${claim.retryAfterMs}ms`);    // backoff hint
+    const result = { chargeId: await doCharge(amount) };      // state === "fresh"
+    const done = await idem.complete(ctx, requestId, result);
+    if (!done.recorded) console.warn("claim lost:", done.reason); // work ran, row gone
+    return result;
+  },
+});
+```
+
+## API Reference
+
+| Method | Kind | Result |
+|--------|------|--------|
+| `begin(ctx, key, opts?)` | mutation | `{ state: "fresh" } \| { state: "inflight"; expiresAt; retryAfterMs } \| { state: "done"; result? }` |
+| `complete(ctx, key, result?, opts?)` | mutation | `{ recorded: true } \| { recorded: false; reason: "missing" \| "expired" \| "already_done" }` |
+| `get(ctx, key, scope?)` | query | `{ status, result?, expiresAt } \| null` |
+| `purge(ctx, opts?)` | mutation | `number` (keys removed in the first bounded pass) |
+
+Full reference: [docs/API.md](docs/API.md).
+
+## React
+
+Backend-only — no `./react` entry. Pure infra dedup with no user-facing reactive surface.
+
+## Security
+
+- Auth-agnostic — the host resolves identity and decides who may run an operation.
+- Tables sandboxed — reached only through the exported functions.
+- Server-sourced expiry — a skewed client clock can't hijack a replay or bypass dedup; `key` / `scope` / `result` stay opaque.
+
+See [docs/API.md](docs/API.md).
+
+## Testing
+
+```bash
+pnpm test           # single run
+pnpm test:coverage  # enforced 100% on covered files
+```
+
+Tests run against the real component runtime via `convex-test` (`@edge-runtime/vm`), not mocks.
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## Author
+
+Built by [bntvllnt](https://github.com/bntvllnt) · [bntvllnt.com](https://bntvllnt.com) · [X @bntvllnt](https://x.com/bntvllnt)
+
+Part of the [@vllnt](https://github.com/vllnt) Convex component fleet — [vllnt.com](https://vllnt.com)
+
+If this is useful, [sponsor the work](https://github.com/sponsors/bntvllnt).
+
+## License
+
+MIT — see [LICENSE](LICENSE).

package/dist/client/index.d.ts

@@ -0,0 +1,135 @@
+import type { FunctionArgs, FunctionReference, FunctionReturnType } from "convex/server";
+import type { BeginResult, CompleteResult, IdempotencyOptions, KeyState, ResultParser } from "./types.js";
+/**
+ * The component's raw `begin` return, before the client narrows `result`. The
+ * stored outcome is opaque here (`unknown`); the {@link Idempotency} client runs
+ * the host `resultValidator` over it at its typed boundary.
+ */
+type RawBegin = {
+    state: "fresh";
+} | {
+    state: "inflight";
+    expiresAt: number;
+    retryAfterMs: number;
+} | {
+    state: "done";
+    result?: unknown;
+};
+/**
+ * The idempotency component's function references, as exposed on the host via
+ * `components.idempotency`. The host's stored outcome type is opaque here
+ * (`unknown`); the {@link Idempotency} client narrows it to `TResult` at its
+ * own typed boundary.
+ */
+export interface IdempotencyComponent {
+    mutations: {
+        begin: FunctionReference<"mutation", "internal", {
+            key: string;
+            scope: string;
+            inflightTtlMs: number;
+        }, RawBegin>;
+        complete: FunctionReference<"mutation", "internal", {
+            key: string;
+            scope: string;
+            result?: unknown;
+            doneTtlMs: number;
+            upsertOnMissing: boolean;
+        }, CompleteResult>;
+        purge: FunctionReference<"mutation", "internal", {
+            before?: number;
+            batch: number;
+        }, number>;
+    };
+    queries: {
+        get: FunctionReference<"query", "internal", {
+            key: string;
+            scope: string;
+        }, {
+            status: "inflight" | "done";
+            result?: unknown;
+            expiresAt: number;
+        } | null>;
+    };
+}
+interface RunQueryCtx {
+    runQuery<Q extends FunctionReference<"query", "internal">>(reference: Q, args: FunctionArgs<Q>): Promise<FunctionReturnType<Q>>;
+}
+interface RunMutationCtx {
+    runMutation<M extends FunctionReference<"mutation", "internal">>(reference: M, args: FunctionArgs<M>): Promise<FunctionReturnType<M>>;
+}
+/** Per-call overrides for `scope` and the inflight lease. */
+interface BeginOptions {
+    scope?: string;
+    inflightTtlMs?: number;
+}
+/** Per-call overrides for `scope`, the done grace window, and lost-claim upsert. */
+interface CompleteOptions {
+    scope?: string;
+    doneTtlMs?: number;
+    upsertOnMissing?: boolean;
+}
+/**
+ * Consumer-facing client for the exactly-once idempotency key ledger. The host
+ * owns meaning and auth; it passes an opaque `key` and an optional `scope`, and
+ * stores an arbitrary `TResult` outcome that replays return verbatim. Pass a
+ * `resultValidator` to narrow the opaque stored value to `TResult` at the
+ * boundary — there is no unchecked cast.
+ *
+ * @typeParam TResult - The host's stored outcome type (defaults to `unknown`).
+ *
+ * @example
+ * ```ts
+ * const idem = new Idempotency(components.idempotency, {
+ *   resultValidator: v.object({ chargeId: v.string() }).parse,
+ * });
+ * const r = await idem.begin(ctx, requestId);
+ * if (r.state === "done") return r.result;                  // typed replay
+ * if (r.state === "inflight") throw new Error(`retry in ${r.retryAfterMs}ms`);
+ * const out = await doWork();                               // r.state === "fresh"
+ * const done = await idem.complete(ctx, requestId, out);
+ * if (!done.recorded) log.warn("claim lost", done.reason);  // work ran, row gone
+ * ```
+ */
+export declare class Idempotency<TResult = unknown> {
+    private readonly component;
+    private readonly defaultScope;
+    private readonly defaultInflightTtlMs;
+    private readonly defaultDoneTtlMs;
+    private readonly defaultUpsertOnMissing;
+    private readonly resultValidator;
+    constructor(component: IdempotencyComponent, options?: IdempotencyOptions<TResult>);
+    private scopeOf;
+    /**
+     * Narrow an opaque stored `result` to `TResult` via the host validator. Absent
+     * values pass through untouched; with no validator the value is returned as-is
+     * (the host accepted the unchecked-type tradeoff by omitting one).
+     */
+    private parseResult;
+    /**
+     * Claim `key`. `fresh` mints an inflight key (do the work, then `complete`);
+     * `inflight` means a concurrent attempt holds it — back off `retryAfterMs`;
+     * `done` returns the validated recorded `result` for a short-circuit replay.
+     */
+    begin(ctx: RunMutationCtx, key: string, opts?: BeginOptions): Promise<BeginResult<TResult>>;
+    /**
+     * Mark `key` `done`, recording `result` and extending the done grace window.
+     * Returns a discriminated outcome: `recorded: true` on success, or
+     * `recorded: false` with a `reason` when the claim was lost (missing, expired,
+     * or already done) so the host can react to dropped work. `result` is validated
+     * against the host validator before it is stored.
+     */
+    complete(ctx: RunMutationCtx, key: string, result?: TResult, opts?: CompleteOptions): Promise<CompleteResult>;
+    /** The stored state for `key`, or `null` if no key is held in the scope. */
+    get(ctx: RunQueryCtx, key: string, scope?: string): Promise<KeyState<TResult> | null>;
+    /**
+     * Delete expired keys in bounded batches, oldest first. `before` defaults to
+     * the server clock; `batch` caps each pass and the sweep self-reschedules until
+     * the tail is clean. Returns the count removed in the first pass.
+     */
+    purge(ctx: RunMutationCtx, opts?: {
+        before?: number;
+        batch?: number;
+    }): Promise<number>;
+}
+export type { BeginResult, CompleteResult, IdempotencyOptions, KeyState, ResultParser, };
+//# sourceMappingURL=index.d.ts.map

package/dist/client/index.d.ts.map

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

package/dist/client/index.js

@@ -0,0 +1,117 @@
+import { DEFAULT_DONE_TTL_MS, DEFAULT_INFLIGHT_TTL_MS, DEFAULT_PURGE_BATCH, DEFAULT_SCOPE, } from "../shared.js";
+/**
+ * Consumer-facing client for the exactly-once idempotency key ledger. The host
+ * owns meaning and auth; it passes an opaque `key` and an optional `scope`, and
+ * stores an arbitrary `TResult` outcome that replays return verbatim. Pass a
+ * `resultValidator` to narrow the opaque stored value to `TResult` at the
+ * boundary — there is no unchecked cast.
+ *
+ * @typeParam TResult - The host's stored outcome type (defaults to `unknown`).
+ *
+ * @example
+ * ```ts
+ * const idem = new Idempotency(components.idempotency, {
+ *   resultValidator: v.object({ chargeId: v.string() }).parse,
+ * });
+ * const r = await idem.begin(ctx, requestId);
+ * if (r.state === "done") return r.result;                  // typed replay
+ * if (r.state === "inflight") throw new Error(`retry in ${r.retryAfterMs}ms`);
+ * const out = await doWork();                               // r.state === "fresh"
+ * const done = await idem.complete(ctx, requestId, out);
+ * if (!done.recorded) log.warn("claim lost", done.reason);  // work ran, row gone
+ * ```
+ */
+export class Idempotency {
+    component;
+    defaultScope;
+    defaultInflightTtlMs;
+    defaultDoneTtlMs;
+    defaultUpsertOnMissing;
+    resultValidator;
+    constructor(component, options = {}) {
+        this.component = component;
+        this.defaultScope = options.defaultScope ?? DEFAULT_SCOPE;
+        this.defaultInflightTtlMs =
+            options.defaultInflightTtlMs ?? DEFAULT_INFLIGHT_TTL_MS;
+        this.defaultDoneTtlMs = options.defaultDoneTtlMs ?? DEFAULT_DONE_TTL_MS;
+        this.defaultUpsertOnMissing = options.upsertOnMissing ?? false;
+        this.resultValidator = options.resultValidator;
+    }
+    scopeOf(scope) {
+        return scope ?? this.defaultScope;
+    }
+    /**
+     * Narrow an opaque stored `result` to `TResult` via the host validator. Absent
+     * values pass through untouched; with no validator the value is returned as-is
+     * (the host accepted the unchecked-type tradeoff by omitting one).
+     */
+    parseResult(value) {
+        if (value === undefined) {
+            return undefined;
+        }
+        if (this.resultValidator === undefined) {
+            return value;
+        }
+        return this.resultValidator(value);
+    }
+    /**
+     * Claim `key`. `fresh` mints an inflight key (do the work, then `complete`);
+     * `inflight` means a concurrent attempt holds it — back off `retryAfterMs`;
+     * `done` returns the validated recorded `result` for a short-circuit replay.
+     */
+    async begin(ctx, key, opts = {}) {
+        const r = await ctx.runMutation(this.component.mutations.begin, {
+            key,
+            scope: this.scopeOf(opts.scope),
+            inflightTtlMs: opts.inflightTtlMs ?? this.defaultInflightTtlMs,
+        });
+        if (r.state === "done") {
+            return { state: "done", result: this.parseResult(r.result) };
+        }
+        return r;
+    }
+    /**
+     * Mark `key` `done`, recording `result` and extending the done grace window.
+     * Returns a discriminated outcome: `recorded: true` on success, or
+     * `recorded: false` with a `reason` when the claim was lost (missing, expired,
+     * or already done) so the host can react to dropped work. `result` is validated
+     * against the host validator before it is stored.
+     */
+    complete(ctx, key, result, opts = {}) {
+        const validated = result === undefined ? undefined : this.parseResult(result);
+        return ctx.runMutation(this.component.mutations.complete, {
+            key,
+            scope: this.scopeOf(opts.scope),
+            result: validated,
+            doneTtlMs: opts.doneTtlMs ?? this.defaultDoneTtlMs,
+            upsertOnMissing: opts.upsertOnMissing ?? this.defaultUpsertOnMissing,
+        });
+    }
+    /** The stored state for `key`, or `null` if no key is held in the scope. */
+    async get(ctx, key, scope) {
+        const row = await ctx.runQuery(this.component.queries.get, {
+            key,
+            scope: this.scopeOf(scope),
+        });
+        if (row === null) {
+            return null;
+        }
+        return {
+            status: row.status,
+            result: this.parseResult(row.result),
+            expiresAt: row.expiresAt,
+        };
+    }
+    /**
+     * Delete expired keys in bounded batches, oldest first. `before` defaults to
+     * the server clock; `batch` caps each pass and the sweep self-reschedules until
+     * the tail is clean. Returns the count removed in the first pass.
+     */
+    purge(ctx, opts = {}) {
+        return ctx.runMutation(this.component.mutations.purge, {
+            before: opts.before,
+            batch: opts.batch ?? DEFAULT_PURGE_BATCH,
+        });
+    }
+}
+//# sourceMappingURL=index.js.map

package/dist/client/index.js.map

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

package/dist/client/types.d.ts

@@ -0,0 +1,78 @@
+/** Public TypeScript surface for the idempotency client. */
+/**
+ * Validates and narrows an opaque stored `result` to the host's `TResult` at the
+ * client boundary. Receives the raw value the component replayed (`unknown`) and
+ * MUST return a typed `TResult` or throw. A `convex/values` validator's `.parse`
+ * (or a Zod `.parse`) fits directly; omit it to keep results unvalidated.
+ *
+ * @typeParam TResult - The host's stored outcome type.
+ */
+export type ResultParser<TResult> = (value: unknown) => TResult;
+/** Outcome of {@link Idempotency.begin} for a key. */
+export type BeginResult<TResult> = {
+    /** The key was just minted; do the work, then call `complete`. */
+    state: "fresh";
+} | {
+    /** Another attempt holds the key; do not re-run. */
+    state: "inflight";
+    /** Absolute ms timestamp when the inflight lease frees. */
+    expiresAt: number;
+    /** How long to back off (ms) before retrying — the crashed-worker self-heal window. */
+    retryAfterMs: number;
+} | {
+    /** A prior attempt already completed; `result` holds its outcome. */
+    state: "done";
+    /** The recorded outcome (absent if completed without one). */
+    result?: TResult;
+};
+/** Outcome of {@link Idempotency.complete} — discriminated so a lost claim is detectable. */
+export type CompleteResult = {
+    /** The outcome was written to the ledger. */
+    recorded: true;
+} | {
+    /** The claim was lost; the work ran but its ledger row was gone. */
+    recorded: false;
+    /**
+     * `missing` — no key for this id/scope. `expired` — the inflight lease
+     * lapsed before completion. `already_done` — a prior attempt won the race.
+     */
+    reason: "missing" | "expired" | "already_done";
+};
+/** Construction options for the {@link Idempotency} client. */
+export interface IdempotencyOptions<TResult> {
+    /** Namespace applied when a call omits `scope`. Default `"global"`. */
+    defaultScope?: string;
+    /**
+     * Inflight lease (ms) applied by `begin` when a call omits `inflightTtlMs`.
+     * Short by design so a crashed worker's claim self-heals. Default `60_000`.
+     */
+    defaultInflightTtlMs?: number;
+    /**
+     * Grace window (ms) applied by `complete` when a call omits `doneTtlMs` —
+     * how long a recorded outcome replays before the key may be re-minted.
+     * Default `86_400_000` (24h).
+     */
+    defaultDoneTtlMs?: number;
+    /**
+     * When set, `complete` upserts the key as `done` even if its inflight row had
+     * vanished (`missing`/`expired`) — recording finished work rather than dropping
+     * it. Default `false`. Overridable per `complete` call.
+     */
+    upsertOnMissing?: boolean;
+    /**
+     * Validates/narrows a stored `result` to `TResult` at the boundary. Applied to
+     * the `result` returned by `begin` (`done` replay) and `get`, and to the
+     * `result` passed into `complete` before it is stored. Throws on a mismatch.
+     */
+    resultValidator?: ResultParser<TResult>;
+}
+/** A key's stored state, as returned by {@link Idempotency.get}. */
+export interface KeyState<TResult> {
+    /** `inflight` while an attempt holds the key, `done` once completed. */
+    status: "inflight" | "done";
+    /** The recorded outcome, present only when `status` is `done`. */
+    result?: TResult;
+    /** Absolute ms timestamp after which the key may be re-minted. */
+    expiresAt: number;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/client/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/client/types.ts"],"names":[],"mappings":"AAAA,4DAA4D;AAE5D;;;;;;;GAOG;AACH,MAAM,MAAM,YAAY,CAAC,OAAO,IAAI,CAAC,KAAK,EAAE,OAAO,KAAK,OAAO,CAAC;AAEhE,sDAAsD;AACtD,MAAM,MAAM,WAAW,CAAC,OAAO,IAC3B;IACE,kEAAkE;IAClE,KAAK,EAAE,OAAO,CAAC;CAChB,GACD;IACE,oDAAoD;IACpD,KAAK,EAAE,UAAU,CAAC;IAClB,2DAA2D;IAC3D,SAAS,EAAE,MAAM,CAAC;IAClB,uFAAuF;IACvF,YAAY,EAAE,MAAM,CAAC;CACtB,GACD;IACE,qEAAqE;IACrE,KAAK,EAAE,MAAM,CAAC;IACd,8DAA8D;IAC9D,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB,CAAC;AAEN,6FAA6F;AAC7F,MAAM,MAAM,cAAc,GACtB;IACE,6CAA6C;IAC7C,QAAQ,EAAE,IAAI,CAAC;CAChB,GACD;IACE,oEAAoE;IACpE,QAAQ,EAAE,KAAK,CAAC;IAChB;;;OAGG;IACH,MAAM,EAAE,SAAS,GAAG,SAAS,GAAG,cAAc,CAAC;CAChD,CAAC;AAEN,+DAA+D;AAC/D,MAAM,WAAW,kBAAkB,CAAC,OAAO;IACzC,uEAAuE;IACvE,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;OAGG;IACH,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B;;;;OAIG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B;;;;OAIG;IACH,eAAe,CAAC,EAAE,YAAY,CAAC,OAAO,CAAC,CAAC;CACzC;AAED,oEAAoE;AACpE,MAAM,WAAW,QAAQ,CAAC,OAAO;IAC/B,wEAAwE;IACxE,MAAM,EAAE,UAAU,GAAG,MAAM,CAAC;IAC5B,kEAAkE;IAClE,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,kEAAkE;IAClE,SAAS,EAAE,MAAM,CAAC;CACnB"}

package/dist/client/types.js

@@ -0,0 +1,3 @@
+/** Public TypeScript surface for the idempotency client. */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/client/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/client/types.ts"],"names":[],"mappings":"AAAA,4DAA4D"}

package/dist/component/_generated/api.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Generated `api` utility.
+ *
+ * THIS CODE IS AUTOMATICALLY GENERATED.
+ *
+ * To regenerate, run `npx convex dev`.
+ * @module
+ */
+import type * as crons from "../crons.js";
+import type * as mutations from "../mutations.js";
+import type * as queries from "../queries.js";
+import type * as validators from "../validators.js";
+import type { ApiFromModules, FilterApi, FunctionReference } from "convex/server";
+declare const fullApi: ApiFromModules<{
+    crons: typeof crons;
+    mutations: typeof mutations;
+    queries: typeof queries;
+    validators: typeof validators;
+}>;
+/**
+ * A utility for referencing Convex functions in your app's public API.
+ *
+ * Usage:
+ * ```js
+ * const myFunctionReference = api.myModule.myFunction;
+ * ```
+ */
+export declare const api: FilterApi<typeof fullApi, FunctionReference<any, "public">>;
+/**
+ * A utility for referencing Convex functions in your app's internal API.
+ *
+ * Usage:
+ * ```js
+ * const myFunctionReference = internal.myModule.myFunction;
+ * ```
+ */
+export declare const internal: FilterApi<typeof fullApi, FunctionReference<any, "internal">>;
+export declare const components: {};
+export {};
+//# sourceMappingURL=api.d.ts.map

package/dist/component/_generated/api.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api.d.ts","sourceRoot":"","sources":["../../../src/component/_generated/api.ts"],"names":[],"mappings":"AACA;;;;;;;GAOG;AAEH,OAAO,KAAK,KAAK,KAAK,MAAM,aAAa,CAAC;AAC1C,OAAO,KAAK,KAAK,SAAS,MAAM,iBAAiB,CAAC;AAClD,OAAO,KAAK,KAAK,OAAO,MAAM,eAAe,CAAC;AAC9C,OAAO,KAAK,KAAK,UAAU,MAAM,kBAAkB,CAAC;AAEpD,OAAO,KAAK,EACV,cAAc,EACd,SAAS,EACT,iBAAiB,EAClB,MAAM,eAAe,CAAC;AAGvB,QAAA,MAAM,OAAO,EAAE,cAAc,CAAC;IAC5B,KAAK,EAAE,OAAO,KAAK,CAAC;IACpB,SAAS,EAAE,OAAO,SAAS,CAAC;IAC5B,OAAO,EAAE,OAAO,OAAO,CAAC;IACxB,UAAU,EAAE,OAAO,UAAU,CAAC;CAC/B,CAAiB,CAAC;AAEnB;;;;;;;GAOG;AACH,eAAO,MAAM,GAAG,EAAE,SAAS,CACzB,OAAO,OAAO,EACd,iBAAiB,CAAC,GAAG,EAAE,QAAQ,CAAC,CACjB,CAAC;AAElB;;;;;;;GAOG;AACH,eAAO,MAAM,QAAQ,EAAE,SAAS,CAC9B,OAAO,OAAO,EACd,iBAAiB,CAAC,GAAG,EAAE,UAAU,CAAC,CACnB,CAAC;AAElB,eAAO,MAAM,UAAU,EAAqC,EAAE,CAAC"}

package/dist/component/_generated/api.js

@@ -0,0 +1,31 @@
+/* eslint-disable */
+/**
+ * Generated `api` utility.
+ *
+ * THIS CODE IS AUTOMATICALLY GENERATED.
+ *
+ * To regenerate, run `npx convex dev`.
+ * @module
+ */
+import { anyApi, componentsGeneric } from "convex/server";
+const fullApi = anyApi;
+/**
+ * A utility for referencing Convex functions in your app's public API.
+ *
+ * Usage:
+ * ```js
+ * const myFunctionReference = api.myModule.myFunction;
+ * ```
+ */
+export const api = anyApi;
+/**
+ * A utility for referencing Convex functions in your app's internal API.
+ *
+ * Usage:
+ * ```js
+ * const myFunctionReference = internal.myModule.myFunction;
+ * ```
+ */
+export const internal = anyApi;
+export const components = componentsGeneric();
+//# sourceMappingURL=api.js.map

package/dist/component/_generated/api.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"api.js","sourceRoot":"","sources":["../../../src/component/_generated/api.ts"],"names":[],"mappings":"AAAA,oBAAoB;AACpB;;;;;;;GAOG;AAYH,OAAO,EAAE,MAAM,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAE1D,MAAM,OAAO,GAKR,MAAa,CAAC;AAEnB;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,GAAG,GAGZ,MAAa,CAAC;AAElB;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,QAAQ,GAGjB,MAAa,CAAC;AAElB,MAAM,CAAC,MAAM,UAAU,GAAG,iBAAiB,EAAmB,CAAC"}

package/dist/component/_generated/component.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Generated `ComponentApi` utility.
+ *
+ * THIS CODE IS AUTOMATICALLY GENERATED.
+ *
+ * To regenerate, run `npx convex dev`.
+ * @module
+ */
+import type { FunctionReference } from "convex/server";
+/**
+ * A utility for referencing a Convex component's exposed API.
+ *
+ * Useful when expecting a parameter like `components.myComponent`.
+ * Usage:
+ * ```ts
+ * async function myFunction(ctx: QueryCtx, component: ComponentApi) {
+ *   return ctx.runQuery(component.someFile.someQuery, { ...args });
+ * }
+ * ```
+ */
+export type ComponentApi<Name extends string | undefined = string | undefined> = {
+    mutations: {
+        begin: FunctionReference<"mutation", "internal", {
+            inflightTtlMs: number;
+            key: string;
+            scope: string;
+        }, {
+            state: "fresh";
+        } | {
+            expiresAt: number;
+            retryAfterMs: number;
+            state: "inflight";
+        } | {
+            result?: any;
+            state: "done";
+        }, Name>;
+        complete: FunctionReference<"mutation", "internal", {
+            doneTtlMs: number;
+            key: string;
+            result?: any;
+            scope: string;
+            upsertOnMissing: boolean;
+        }, {
+            recorded: true;
+        } | {
+            reason: "missing" | "expired" | "already_done";
+            recorded: false;
+        }, Name>;
+        purge: FunctionReference<"mutation", "internal", {
+            batch: number;
+            before?: number;
+        }, number, Name>;
+    };
+    queries: {
+        get: FunctionReference<"query", "internal", {
+            key: string;
+            scope: string;
+        }, null | {
+            expiresAt: number;
+            result?: any;
+            status: "inflight" | "done";
+        }, Name>;
+    };
+};
+//# sourceMappingURL=component.d.ts.map

package/dist/component/_generated/component.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"component.d.ts","sourceRoot":"","sources":["../../../src/component/_generated/component.ts"],"names":[],"mappings":"AACA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAEvD;;;;;;;;;;GAUG;AACH,MAAM,MAAM,YAAY,CAAC,IAAI,SAAS,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,IAC3E;IACE,SAAS,EAAE;QACT,KAAK,EAAE,iBAAiB,CACtB,UAAU,EACV,UAAU,EACV;YAAE,aAAa,EAAE,MAAM,CAAC;YAAC,GAAG,EAAE,MAAM,CAAC;YAAC,KAAK,EAAE,MAAM,CAAA;SAAE,EACnD;YAAE,KAAK,EAAE,OAAO,CAAA;SAAE,GAClB;YAAE,SAAS,EAAE,MAAM,CAAC;YAAC,YAAY,EAAE,MAAM,CAAC;YAAC,KAAK,EAAE,UAAU,CAAA;SAAE,GAC9D;YAAE,MAAM,CAAC,EAAE,GAAG,CAAC;YAAC,KAAK,EAAE,MAAM,CAAA;SAAE,EACjC,IAAI,CACL,CAAC;QACF,QAAQ,EAAE,iBAAiB,CACzB,UAAU,EACV,UAAU,EACV;YACE,SAAS,EAAE,MAAM,CAAC;YAClB,GAAG,EAAE,MAAM,CAAC;YACZ,MAAM,CAAC,EAAE,GAAG,CAAC;YACb,KAAK,EAAE,MAAM,CAAC;YACd,eAAe,EAAE,OAAO,CAAC;SAC1B,EACC;YAAE,QAAQ,EAAE,IAAI,CAAA;SAAE,GAClB;YAAE,MAAM,EAAE,SAAS,GAAG,SAAS,GAAG,cAAc,CAAC;YAAC,QAAQ,EAAE,KAAK,CAAA;SAAE,EACrE,IAAI,CACL,CAAC;QACF,KAAK,EAAE,iBAAiB,CACtB,UAAU,EACV,UAAU,EACV;YAAE,KAAK,EAAE,MAAM,CAAC;YAAC,MAAM,CAAC,EAAE,MAAM,CAAA;SAAE,EAClC,MAAM,EACN,IAAI,CACL,CAAC;KACH,CAAC;IACF,OAAO,EAAE;QACP,GAAG,EAAE,iBAAiB,CACpB,OAAO,EACP,UAAU,EACV;YAAE,GAAG,EAAE,MAAM,CAAC;YAAC,KAAK,EAAE,MAAM,CAAA;SAAE,EAC9B,IAAI,GAAG;YAAE,SAAS,EAAE,MAAM,CAAC;YAAC,MAAM,CAAC,EAAE,GAAG,CAAC;YAAC,MAAM,EAAE,UAAU,GAAG,MAAM,CAAA;SAAE,EACvE,IAAI,CACL,CAAC;KACH,CAAC;CACH,CAAC"}