@vllnt/convex-suppression 0.1.0-canary.261f634

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,138 @@
+<!-- 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-suppression.svg)](https://www.npmjs.com/package/@vllnt/convex-suppression)
+[![CI](https://github.com/vllnt/convex-suppression/actions/workflows/ci.yml/badge.svg)](https://github.com/vllnt/convex-suppression/actions/workflows/ci.yml)
+[![license](https://img.shields.io/npm/l/@vllnt/convex-suppression.svg)](./LICENSE)
+
+# @vllnt/convex-suppression
+
+The do-not-contact suppression list + opt-in proof, as a Convex component.
+
+```ts
+const dnc = new Suppression(components.suppression);
+await dnc.suppress(ctx, contactHash, "complaint", { channel: "email" });
+const canSend = await dnc.isEligible(ctx, contactHash, { channel: "email" });
+```
+
+The GDPR opt-out / CAN-SPAM primitive: a global do-not-contact list keyed by an
+opaque **`contactHash`** (never raw PII, so it survives erasure) plus an opt-in
+proof ledger. Before every send the host asks `isEligible`; an unsubscribe / bounce
+/ complaint calls `suppress`; a double-opt-in confirmation calls `recordOptIn`.
+Domain-neutral — channels and reasons are the host's.
+
+## Features
+
+- **Hash-keyed, erasure-surviving** — stores only the opaque `contactHash`, never raw PII, so a tombstone outlives erasure of the subject.
+- **Channel-aware** — scope a suppression to one channel (`"email"`/`"sms"`/`"push"`), or omit `channel` for a global all-channel tombstone.
+- **One send gate** — `isEligible` answers `¬suppressed [∧ confirmed]` in one call; suppression always blocks, opt-in is per call.
+- **Opt-in proof ledger** — `recordOptIn` / `getOptInProof` store legal proof-of-consent per list, kept separate from any authz store.
+- **Idempotent** — re-suppressing / re-recording on its key tuple updates in place, so a replayed webhook never duplicates a row.
+- **Typed, opaque proof** — `Suppression<TProof>` with an optional `proofValidator` narrows the stored evidence at the boundary.
+- **Server-sourced time** — `createdAt`/`confirmedAt` are stamped from the server clock; a caller can never supply a timestamp.
+- **Mount-safe** — correct under multiple named `app.use` mounts (e.g. marketing vs. transactional lists), each an isolated sandbox.
+
+## Installation
+
+```bash
+pnpm add @vllnt/convex-suppression
+```
+
+Peer dependency: `convex@^1.41.0`.
+
+## Usage
+
+```ts
+// convex/convex.config.ts
+import { defineApp } from "convex/server";
+import suppression from "@vllnt/convex-suppression/convex.config";
+
+const app = defineApp();
+app.use(suppression);
+export default app;
+```
+
+```ts
+// convex/email.ts — host owns auth + hashing; pass an opaque contactHash in.
+import { components } from "./_generated/api";
+import { mutation, query } from "./_generated/server";
+import { v } from "convex/values";
+import { Suppression } from "@vllnt/convex-suppression";
+
+const dnc = new Suppression<{ ip: string }>(components.suppression, {
+  proofValidator: v.object({ ip: v.string() }).parse,
+});
+const hash = (email: string) => myHash(email.trim().toLowerCase()); // host's hashing + salt policy
+
+// The send gate — call before every send.
+export const canEmail = query({
+  args: { email: v.string() },
+  handler: (ctx, { email }) =>
+    dnc.isEligible(ctx, hash(email), { channel: "email", listKey: "newsletter", requireOptIn: true }),
+});
+
+// A provider webhook suppresses on complaint; a confirmed double opt-in records proof.
+export const onComplaint = mutation({
+  args: { email: v.string() },
+  handler: (ctx, { email }) => dnc.suppress(ctx, hash(email), "complaint", { channel: "email" }),
+});
+export const confirmOptIn = mutation({
+  args: { email: v.string(), ip: v.string() },
+  handler: (ctx, { email, ip }) =>
+    dnc.recordOptIn(ctx, hash(email), { listKey: "newsletter", source: "double-opt-in", proof: { ip } }),
+});
+```
+
+Client options: `new Suppression(component, { proofValidator? })`. Omitting `channel`/`listKey` targets the global entry.
+
+## API Reference
+
+| Method | Kind | Result |
+|--------|------|--------|
+| `suppress(ctx, contactHash, reason, opts?)` | mutation | `null` (`reason`: `"unsubscribe" \| "bounce" \| "complaint" \| "manual" \| "global"`; `opts`: `{ channel? }`) |
+| `unsuppress(ctx, contactHash, channel?)` | mutation | `boolean` (`true` if an entry was removed) |
+| `recordOptIn(ctx, contactHash, opts)` | mutation | `null` (`opts`: `{ listKey?; source; proof? }`) |
+| `isSuppressed(ctx, contactHash, channel?)` | query | `SuppressionView \| null` |
+| `getOptInProof(ctx, contactHash, listKey?)` | query | `OptInProofView \| null` |
+| `isEligible(ctx, contactHash, opts?)` | query | `boolean` (`opts`: `{ channel?; listKey?; requireOptIn? }`) |
+
+Full reference: [docs/API.md](docs/API.md).
+
+## React
+
+Backend-only — no `./react` entry. The consumer surface is a server-side
+`isEligible` gate and webhook-driven `suppress` writes; a reactive do-not-contact
+badge, if ever needed, is an ordinary `useQuery` over the host's re-exported
+`isSuppressed` ref.
+
+## Security
+
+- **Auth-agnostic** — the host authenticates the caller, decides who may suppress/query a hash, and passes an opaque `contactHash`; tables are sandboxed.
+- **Hash-keyed, never raw PII** — the host hashes and normalizes the contact and owns the salt policy; a suppression survives erasure of the subject.
+- **Server-sourced time** — `createdAt`/`confirmedAt` come from `Date.now()` in each handler, never the caller; the opt-in `proof` is opaque, narrowed by the host validator.
+
+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 { IsEligibleOptions, OptInProofView, Parser, RecordOptInOptions, SuppressionOptions, SuppressionReason, SuppressionView, SuppressOptions } from "./types.js";
+/**
+ * The component's raw opt-in proof view, before the client narrows opaque host
+ * evidence. `proof` is `unknown` here; the {@link Suppression} client runs the
+ * host validator over it at its typed boundary.
+ */
+type RawProofView = {
+    contactHash: string;
+    listKey: string | null;
+    source: string;
+    proof?: unknown;
+    confirmedAt: number;
+};
+/**
+ * The suppression component's function references, as exposed on the host via
+ * `components.suppression`. The host's stored opt-in `proof` is opaque here
+ * (`unknown`); the {@link Suppression} client narrows it at its own typed boundary.
+ */
+export interface SuppressionComponent {
+    mutations: {
+        suppress: FunctionReference<"mutation", "internal", {
+            contactHash: string;
+            channel: string;
+            reason: SuppressionReason;
+        }, null>;
+        unsuppress: FunctionReference<"mutation", "internal", {
+            contactHash: string;
+            channel: string;
+        }, boolean>;
+        recordOptIn: FunctionReference<"mutation", "internal", {
+            contactHash: string;
+            listKey: string;
+            source: string;
+            proof?: unknown;
+        }, null>;
+    };
+    queries: {
+        isSuppressed: FunctionReference<"query", "internal", {
+            contactHash: string;
+            channel: string;
+        }, SuppressionView | null>;
+        getOptInProof: FunctionReference<"query", "internal", {
+            contactHash: string;
+            listKey: string;
+        }, RawProofView | null>;
+        isEligible: FunctionReference<"query", "internal", {
+            contactHash: string;
+            channel: string;
+            listKey: string;
+            requireOptIn: boolean;
+        }, boolean>;
+    };
+}
+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>>;
+}
+/**
+ * Consumer-facing client for the do-not-contact suppression gate (GDPR opt-out /
+ * CAN-SPAM). The host hashes a contact (`hash(normalize(email|phone))`) and passes
+ * the opaque `contactHash`; the component stores a `(contactHash, channel)`
+ * anti-membership tombstone that survives erasure of the subject. A sender calls
+ * `isEligible` before every send (`¬suppressed [∧ confirmed]`); an unsubscribe /
+ * bounce / complaint webhook calls `suppress`; a double-opt-in confirmation calls
+ * `recordOptIn`. The host owns meaning and auth — it resolves identity, hashes the
+ * contact, and decides the channel/list semantics. Pass `proofValidator` to narrow
+ * the opaque opt-in evidence to `TProof` at the boundary — there is no unchecked
+ * cast.
+ *
+ * @typeParam TProof - The host's opt-in proof evidence type (defaults to `unknown`).
+ *
+ * @example
+ * ```ts
+ * const dnc = new Suppression(components.suppression, {
+ *   proofValidator: v.object({ ip: v.string() }).parse,
+ * });
+ * // a webhook suppresses on complaint:
+ * await dnc.suppress(ctx, contactHash, "complaint", { channel: "email" });
+ * // a sender gates a marketing send:
+ * if (await dnc.isEligible(ctx, contactHash, { channel: "email", listKey: "news", requireOptIn: true })) {
+ *   // ...send
+ * }
+ * ```
+ */
+export declare class Suppression<TProof = unknown> {
+    private readonly component;
+    private readonly proofValidator;
+    constructor(component: SuppressionComponent, options?: SuppressionOptions<TProof>);
+    /** Narrow an opaque value through a host parser; pass `undefined` and unset parsers through. */
+    private parse;
+    /**
+     * Suppress a `(contactHash, channel)` — add it to the do-not-contact list.
+     * `opts.channel` scopes the suppression to one channel; omit it for a global
+     * (all-channel) suppression. Idempotent on `(contactHash, channel)`. `reason` is
+     * recorded for audit.
+     */
+    suppress(ctx: RunMutationCtx, contactHash: string, reason: SuppressionReason, opts?: SuppressOptions): Promise<null>;
+    /**
+     * Remove a `(contactHash, channel)` from the do-not-contact list (a rare,
+     * audited re-subscribe). Omit `channel` to clear the global entry. Returns `true`
+     * if an entry was removed, `false` if none matched.
+     */
+    unsuppress(ctx: RunMutationCtx, contactHash: string, channel?: string): Promise<boolean>;
+    /**
+     * The matching suppression for `(contactHash, channel)`, or `null` if the
+     * contact is not suppressed on that channel. A global suppression matches every
+     * channel and wins. Omit `channel` to check the global entry only.
+     */
+    isSuppressed(ctx: RunQueryCtx, contactHash: string, channel?: string): Promise<SuppressionView | null>;
+    /**
+     * Record an opt-in proof for a `(contactHash, listKey)` — the legal evidence of
+     * a confirmed opt-in. `opts.listKey` scopes the proof to one list; omit it for a
+     * global opt-in. `opts.proof` is opaque host evidence validated against
+     * `proofValidator` before storage. Idempotent on `(contactHash, listKey)`.
+     */
+    recordOptIn(ctx: RunMutationCtx, contactHash: string, opts: RecordOptInOptions<TProof>): Promise<null>;
+    /**
+     * The opt-in proof for `(contactHash, listKey)`, or `null` if none is recorded.
+     * Omit `listKey` to fetch a global opt-in. `proof` is narrowed by the host
+     * validator on read.
+     */
+    getOptInProof(ctx: RunQueryCtx, contactHash: string, listKey?: string): Promise<OptInProofView<TProof> | null>;
+    /**
+     * The send gate: `true` when the contact may be contacted — NOT suppressed on
+     * `opts.channel` (global or channel-specific) and, when `opts.requireOptIn` is
+     * set, holding a recorded opt-in proof for `opts.listKey`. Suppression always
+     * blocks; the opt-in requirement is per call.
+     */
+    isEligible(ctx: RunQueryCtx, contactHash: string, opts?: IsEligibleOptions): Promise<boolean>;
+}
+export type { IsEligibleOptions, OptInProofView, Parser, RecordOptInOptions, SuppressionOptions, SuppressionReason, SuppressionView, SuppressOptions, };
+//# 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,131 @@
+import { GLOBAL_CHANNEL } from "../shared.js";
+/**
+ * Consumer-facing client for the do-not-contact suppression gate (GDPR opt-out /
+ * CAN-SPAM). The host hashes a contact (`hash(normalize(email|phone))`) and passes
+ * the opaque `contactHash`; the component stores a `(contactHash, channel)`
+ * anti-membership tombstone that survives erasure of the subject. A sender calls
+ * `isEligible` before every send (`¬suppressed [∧ confirmed]`); an unsubscribe /
+ * bounce / complaint webhook calls `suppress`; a double-opt-in confirmation calls
+ * `recordOptIn`. The host owns meaning and auth — it resolves identity, hashes the
+ * contact, and decides the channel/list semantics. Pass `proofValidator` to narrow
+ * the opaque opt-in evidence to `TProof` at the boundary — there is no unchecked
+ * cast.
+ *
+ * @typeParam TProof - The host's opt-in proof evidence type (defaults to `unknown`).
+ *
+ * @example
+ * ```ts
+ * const dnc = new Suppression(components.suppression, {
+ *   proofValidator: v.object({ ip: v.string() }).parse,
+ * });
+ * // a webhook suppresses on complaint:
+ * await dnc.suppress(ctx, contactHash, "complaint", { channel: "email" });
+ * // a sender gates a marketing send:
+ * if (await dnc.isEligible(ctx, contactHash, { channel: "email", listKey: "news", requireOptIn: true })) {
+ *   // ...send
+ * }
+ * ```
+ */
+export class Suppression {
+    component;
+    proofValidator;
+    constructor(component, options = {}) {
+        this.component = component;
+        this.proofValidator = options.proofValidator;
+    }
+    /** Narrow an opaque value through a host parser; pass `undefined` and unset parsers through. */
+    parse(value) {
+        if (value === undefined) {
+            return undefined;
+        }
+        if (this.proofValidator === undefined) {
+            return value;
+        }
+        return this.proofValidator(value);
+    }
+    /**
+     * Suppress a `(contactHash, channel)` — add it to the do-not-contact list.
+     * `opts.channel` scopes the suppression to one channel; omit it for a global
+     * (all-channel) suppression. Idempotent on `(contactHash, channel)`. `reason` is
+     * recorded for audit.
+     */
+    suppress(ctx, contactHash, reason, opts = {}) {
+        return ctx.runMutation(this.component.mutations.suppress, {
+            contactHash,
+            channel: opts.channel ?? GLOBAL_CHANNEL,
+            reason,
+        });
+    }
+    /**
+     * Remove a `(contactHash, channel)` from the do-not-contact list (a rare,
+     * audited re-subscribe). Omit `channel` to clear the global entry. Returns `true`
+     * if an entry was removed, `false` if none matched.
+     */
+    unsuppress(ctx, contactHash, channel) {
+        return ctx.runMutation(this.component.mutations.unsuppress, {
+            contactHash,
+            channel: channel ?? GLOBAL_CHANNEL,
+        });
+    }
+    /**
+     * The matching suppression for `(contactHash, channel)`, or `null` if the
+     * contact is not suppressed on that channel. A global suppression matches every
+     * channel and wins. Omit `channel` to check the global entry only.
+     */
+    isSuppressed(ctx, contactHash, channel) {
+        return ctx.runQuery(this.component.queries.isSuppressed, {
+            contactHash,
+            channel: channel ?? GLOBAL_CHANNEL,
+        });
+    }
+    /**
+     * Record an opt-in proof for a `(contactHash, listKey)` — the legal evidence of
+     * a confirmed opt-in. `opts.listKey` scopes the proof to one list; omit it for a
+     * global opt-in. `opts.proof` is opaque host evidence validated against
+     * `proofValidator` before storage. Idempotent on `(contactHash, listKey)`.
+     */
+    recordOptIn(ctx, contactHash, opts) {
+        return ctx.runMutation(this.component.mutations.recordOptIn, {
+            contactHash,
+            listKey: opts.listKey ?? GLOBAL_CHANNEL,
+            source: opts.source,
+            proof: opts.proof === undefined ? undefined : this.parse(opts.proof),
+        });
+    }
+    /**
+     * The opt-in proof for `(contactHash, listKey)`, or `null` if none is recorded.
+     * Omit `listKey` to fetch a global opt-in. `proof` is narrowed by the host
+     * validator on read.
+     */
+    async getOptInProof(ctx, contactHash, listKey) {
+        const raw = await ctx.runQuery(this.component.queries.getOptInProof, {
+            contactHash,
+            listKey: listKey ?? GLOBAL_CHANNEL,
+        });
+        if (raw === null) {
+            return null;
+        }
+        return {
+            contactHash: raw.contactHash,
+            listKey: raw.listKey,
+            source: raw.source,
+            proof: this.parse(raw.proof),
+            confirmedAt: raw.confirmedAt,
+        };
+    }
+    /**
+     * The send gate: `true` when the contact may be contacted — NOT suppressed on
+     * `opts.channel` (global or channel-specific) and, when `opts.requireOptIn` is
+     * set, holding a recorded opt-in proof for `opts.listKey`. Suppression always
+     * blocks; the opt-in requirement is per call.
+     */
+    isEligible(ctx, contactHash, opts = {}) {
+        return ctx.runQuery(this.component.queries.isEligible, {
+            contactHash,
+            channel: opts.channel ?? GLOBAL_CHANNEL,
+            listKey: opts.listKey ?? GLOBAL_CHANNEL,
+            requireOptIn: opts.requireOptIn ?? false,
+        });
+    }
+}
+//# 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,70 @@
+/** Public TypeScript surface for the suppression client. */
+/** The five standard reasons a `(contactHash, channel)` is suppressed. */
+export type SuppressionReason = "unsubscribe" | "bounce" | "complaint" | "manual" | "global";
+/**
+ * Validates and narrows opaque host opt-in evidence to a host type `T` at the
+ * client boundary. Receives the raw value the component returned (`unknown`) and
+ * MUST return a typed `T` or throw. A `convex/values` validator's `.parse` (or a
+ * Zod `.parse`) fits directly; omit it to keep the value unvalidated.
+ *
+ * @typeParam T - The host's stored opt-in `proof` type.
+ */
+export type Parser<T> = (value: unknown) => T;
+/** The public view of a suppression returned by {@link Suppression.isSuppressed}. */
+export interface SuppressionView {
+    /** The host's opaque contact hash — never a raw email/phone. */
+    contactHash: string;
+    /** The channel this entry applies to, or `null` for a global (all-channel) suppression. */
+    channel: string | null;
+    /** Why the contact was suppressed (audit only — never changes the effect). */
+    reason: SuppressionReason;
+    /** Absolute ms timestamp the suppression was recorded. */
+    createdAt: number;
+}
+/** The public view of an opt-in proof returned by {@link Suppression.getOptInProof}. */
+export interface OptInProofView<TProof = unknown> {
+    /** The host's opaque contact hash. */
+    contactHash: string;
+    /** The list/purpose the opt-in applies to, or `null` for a global opt-in. */
+    listKey: string | null;
+    /** How the opt-in was captured (e.g. `"double-opt-in"`, `"checkbox"`). */
+    source: string;
+    /** The opaque host evidence (narrowed if a `proofValidator` is set). */
+    proof?: TProof;
+    /** Absolute ms timestamp the opt-in was confirmed. */
+    confirmedAt: number;
+}
+/** Per-call options for {@link Suppression.suppress}. */
+export interface SuppressOptions {
+    /** The channel to suppress (`"email"`/`"sms"`/…). Omit for a global suppression. */
+    channel?: string;
+}
+/** Per-call options for {@link Suppression.recordOptIn}. */
+export interface RecordOptInOptions<TProof> {
+    /** The list/purpose the opt-in applies to. Omit for a global opt-in. */
+    listKey?: string;
+    /** How the opt-in was captured. */
+    source: string;
+    /** Opaque host evidence (validated against `proofValidator` before storage). */
+    proof?: TProof;
+}
+/** Per-call options for {@link Suppression.isEligible}. */
+export interface IsEligibleOptions {
+    /** The channel to check (`"email"`/`"sms"`/…). Omit to check the global gate only. */
+    channel?: string;
+    /** The list/purpose to require an opt-in for (used only when `requireOptIn`). */
+    listKey?: string;
+    /** When `true`, also require a recorded opt-in proof for `listKey`. */
+    requireOptIn?: boolean;
+}
+/** Construction options for the {@link Suppression} client. */
+export interface SuppressionOptions<TProof> {
+    /**
+     * Validates/narrows opaque opt-in `proof` to `TProof` at the boundary — applied
+     * to the `proof` passed into `recordOptIn` (before storage) and the `proof`
+     * returned by `getOptInProof` (on read). Throws on a mismatch. Omit to leave
+     * proof evidence unvalidated.
+     */
+    proofValidator?: Parser<TProof>;
+}
+//# 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,0EAA0E;AAC1E,MAAM,MAAM,iBAAiB,GACzB,aAAa,GACb,QAAQ,GACR,WAAW,GACX,QAAQ,GACR,QAAQ,CAAC;AAEb;;;;;;;GAOG;AACH,MAAM,MAAM,MAAM,CAAC,CAAC,IAAI,CAAC,KAAK,EAAE,OAAO,KAAK,CAAC,CAAC;AAE9C,qFAAqF;AACrF,MAAM,WAAW,eAAe;IAC9B,gEAAgE;IAChE,WAAW,EAAE,MAAM,CAAC;IACpB,2FAA2F;IAC3F,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,8EAA8E;IAC9E,MAAM,EAAE,iBAAiB,CAAC;IAC1B,0DAA0D;IAC1D,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,wFAAwF;AACxF,MAAM,WAAW,cAAc,CAAC,MAAM,GAAG,OAAO;IAC9C,sCAAsC;IACtC,WAAW,EAAE,MAAM,CAAC;IACpB,6EAA6E;IAC7E,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,0EAA0E;IAC1E,MAAM,EAAE,MAAM,CAAC;IACf,wEAAwE;IACxE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,sDAAsD;IACtD,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,yDAAyD;AACzD,MAAM,WAAW,eAAe;IAC9B,oFAAoF;IACpF,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,4DAA4D;AAC5D,MAAM,WAAW,kBAAkB,CAAC,MAAM;IACxC,wEAAwE;IACxE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,mCAAmC;IACnC,MAAM,EAAE,MAAM,CAAC;IACf,gFAAgF;IAChF,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,2DAA2D;AAC3D,MAAM,WAAW,iBAAiB;IAChC,sFAAsF;IACtF,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,iFAAiF;IACjF,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,uEAAuE;IACvE,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB;AAED,+DAA+D;AAC/D,MAAM,WAAW,kBAAkB,CAAC,MAAM;IACxC;;;;;OAKG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC;CACjC"}

package/dist/client/types.js

@@ -0,0 +1,3 @@
+/** Public TypeScript surface for the suppression 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,38 @@
+/**
+ * Generated `api` utility.
+ *
+ * THIS CODE IS AUTOMATICALLY GENERATED.
+ *
+ * To regenerate, run `npx convex dev`.
+ * @module
+ */
+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<{
+    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,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,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;AAWH,OAAO,EAAE,MAAM,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAE1D,MAAM,OAAO,GAIR,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"}