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

package/dist/component/queries.js

@@ -0,0 +1,112 @@
+import { v } from "convex/values";
+import { query } from "./_generated/server";
+import { GLOBAL_CHANNEL } from "../shared";
+import { optInProofView, suppressionView } from "./validators";
+/** Project a stored suppression row to its public view (drops internal fields). */
+function view(row) {
+    return {
+        contactHash: row.contactHash,
+        channel: row.channel === GLOBAL_CHANNEL ? null : row.channel,
+        reason: row.reason,
+        createdAt: row.createdAt,
+    };
+}
+/**
+ * The matching suppression for `(contactHash, channel)`, or `null` if the contact
+ * is not suppressed on that channel. A `channel` argument matches a global
+ * (all-channel) suppression OR a channel-specific one — a global tombstone wins
+ * and is returned first. Omit `channel` (the sentinel) to check the global entry
+ * only. Two bounded equality reads on `by_hash_channel`; never spans contacts.
+ */
+export const isSuppressed = query({
+    args: { contactHash: v.string(), channel: v.string() },
+    returns: v.union(v.null(), suppressionView),
+    handler: async (ctx, args) => {
+        const globalRow = await ctx.db
+            .query("suppressions")
+            .withIndex("by_hash_channel", (q) => q.eq("contactHash", args.contactHash).eq("channel", GLOBAL_CHANNEL))
+            .unique();
+        if (globalRow !== null) {
+            return view(globalRow);
+        }
+        if (args.channel === GLOBAL_CHANNEL) {
+            return null;
+        }
+        const channelRow = await ctx.db
+            .query("suppressions")
+            .withIndex("by_hash_channel", (q) => q.eq("contactHash", args.contactHash).eq("channel", args.channel))
+            .unique();
+        return channelRow === null ? null : view(channelRow);
+    },
+});
+/**
+ * The opt-in proof for `(contactHash, listKey)`, or `null` if none is recorded.
+ * `listKey` holds the global sentinel to fetch a global opt-in. `proof` is the
+ * opaque host evidence, narrowed by the host validator at the client boundary.
+ */
+export const getOptInProof = query({
+    args: { contactHash: v.string(), listKey: v.string() },
+    returns: v.union(v.null(), optInProofView),
+    handler: async (ctx, args) => {
+        const row = await ctx.db
+            .query("optInProofs")
+            .withIndex("by_hash_list", (q) => q.eq("contactHash", args.contactHash).eq("listKey", args.listKey))
+            .unique();
+        if (row === null) {
+            return null;
+        }
+        return {
+            contactHash: row.contactHash,
+            listKey: row.listKey === GLOBAL_CHANNEL ? null : row.listKey,
+            source: row.source,
+            proof: row.proof,
+            confirmedAt: row.confirmedAt,
+        };
+    },
+});
+/**
+ * The send gate: `true` when the contact may be contacted. A contact is eligible
+ * when it is NOT suppressed on `channel` (global or channel-specific) and — when
+ * `requireOptIn` is set — has a recorded opt-in proof for `listKey`. This is the
+ * single call a sender makes before every send: `¬suppressed [∧ confirmed]`.
+ * Suppression always blocks; the opt-in requirement is opt-in per call (marketing
+ * mail sets it; a transactional send may not).
+ */
+export const isEligible = query({
+    args: {
+        contactHash: v.string(),
+        channel: v.string(),
+        listKey: v.string(),
+        requireOptIn: v.boolean(),
+    },
+    returns: v.boolean(),
+    handler: async (ctx, args) => {
+        const globalRow = await ctx.db
+            .query("suppressions")
+            .withIndex("by_hash_channel", (q) => q.eq("contactHash", args.contactHash).eq("channel", GLOBAL_CHANNEL))
+            .unique();
+        if (globalRow !== null) {
+            return false;
+        }
+        if (args.channel !== GLOBAL_CHANNEL) {
+            const channelRow = await ctx.db
+                .query("suppressions")
+                .withIndex("by_hash_channel", (q) => q.eq("contactHash", args.contactHash).eq("channel", args.channel))
+                .unique();
+            if (channelRow !== null) {
+                return false;
+            }
+        }
+        if (args.requireOptIn) {
+            const proof = await ctx.db
+                .query("optInProofs")
+                .withIndex("by_hash_list", (q) => q.eq("contactHash", args.contactHash).eq("listKey", args.listKey))
+                .unique();
+            if (proof === null) {
+                return false;
+            }
+        }
+        return true;
+    },
+});
+//# sourceMappingURL=queries.js.map

package/dist/component/queries.js.map

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

package/dist/component/schema.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Two sandboxed tables — the do-not-contact gate's own concern.
+ *
+ * `suppressions` is the anti-membership: a `(contactHash, channel)` tombstone that
+ * says "never contact this hash on this channel". `contactHash` is the host's
+ * opaque `hash(normalize(contact))` — the component never stores a raw email or
+ * phone, so a suppression survives erasure of the underlying subject. `channel`
+ * holds the host channel (`"email"`/`"sms"`/…) or the `GLOBAL_CHANNEL` sentinel
+ * `"*"` for an all-channel suppression. `reason` is recorded for audit. Indexed
+ * `by_hash_channel` (the exact-channel and global lookups an `isSuppressed` check
+ * makes) and `by_hash` (every entry for a hash, for `unsuppress` and audit).
+ *
+ * `optInProofs` is the legal evidence (not an authz relation): a `(contactHash,
+ * listKey)` record of a confirmed opt-in. `listKey` scopes it to one list/purpose
+ * or holds `GLOBAL_CHANNEL` for a global opt-in; `source` tags the capture
+ * channel; `proof` is opaque host evidence narrowed by a host validator. Indexed
+ * `by_hash_list` (the exact lookup `getOptInProof`/`isEligible` make).
+ */
+declare const _default: import("convex/server").SchemaDefinition<{
+    suppressions: import("convex/server").TableDefinition<import("convex/values").VObject<{
+        contactHash: string;
+        channel: string;
+        reason: "unsubscribe" | "bounce" | "complaint" | "manual" | "global";
+        createdAt: number;
+    }, {
+        contactHash: import("convex/values").VString<string, "required">;
+        channel: import("convex/values").VString<string, "required">;
+        reason: import("convex/values").VUnion<"unsubscribe" | "bounce" | "complaint" | "manual" | "global", [import("convex/values").VLiteral<"unsubscribe", "required">, import("convex/values").VLiteral<"bounce", "required">, import("convex/values").VLiteral<"complaint", "required">, import("convex/values").VLiteral<"manual", "required">, import("convex/values").VLiteral<"global", "required">], "required", never>;
+        createdAt: import("convex/values").VFloat64<number, "required">;
+    }, "required", "contactHash" | "channel" | "reason" | "createdAt">, {
+        by_hash: ["contactHash", "_creationTime"];
+        by_hash_channel: ["contactHash", "channel", "_creationTime"];
+    }, {}, {}>;
+    optInProofs: import("convex/server").TableDefinition<import("convex/values").VObject<{
+        proof?: any;
+        contactHash: string;
+        listKey: string;
+        source: string;
+        confirmedAt: number;
+    }, {
+        contactHash: import("convex/values").VString<string, "required">;
+        listKey: import("convex/values").VString<string, "required">;
+        source: import("convex/values").VString<string, "required">;
+        proof: import("convex/values").VAny<any, "optional", string>;
+        confirmedAt: import("convex/values").VFloat64<number, "required">;
+    }, "required", "contactHash" | "listKey" | "source" | "proof" | "confirmedAt" | `proof.${string}`>, {
+        by_hash_list: ["contactHash", "listKey", "_creationTime"];
+    }, {}, {}>;
+}, true>;
+export default _default;
+//# sourceMappingURL=schema.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../src/component/schema.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;GAiBG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AACH,wBAiBG"}

package/dist/component/schema.js

@@ -0,0 +1,39 @@
+import { defineSchema, defineTable } from "convex/server";
+import { v } from "convex/values";
+import { jsonValue, suppressionReason } from "./validators";
+/**
+ * Two sandboxed tables — the do-not-contact gate's own concern.
+ *
+ * `suppressions` is the anti-membership: a `(contactHash, channel)` tombstone that
+ * says "never contact this hash on this channel". `contactHash` is the host's
+ * opaque `hash(normalize(contact))` — the component never stores a raw email or
+ * phone, so a suppression survives erasure of the underlying subject. `channel`
+ * holds the host channel (`"email"`/`"sms"`/…) or the `GLOBAL_CHANNEL` sentinel
+ * `"*"` for an all-channel suppression. `reason` is recorded for audit. Indexed
+ * `by_hash_channel` (the exact-channel and global lookups an `isSuppressed` check
+ * makes) and `by_hash` (every entry for a hash, for `unsuppress` and audit).
+ *
+ * `optInProofs` is the legal evidence (not an authz relation): a `(contactHash,
+ * listKey)` record of a confirmed opt-in. `listKey` scopes it to one list/purpose
+ * or holds `GLOBAL_CHANNEL` for a global opt-in; `source` tags the capture
+ * channel; `proof` is opaque host evidence narrowed by a host validator. Indexed
+ * `by_hash_list` (the exact lookup `getOptInProof`/`isEligible` make).
+ */
+export default defineSchema({
+    suppressions: defineTable({
+        contactHash: v.string(),
+        channel: v.string(),
+        reason: suppressionReason,
+        createdAt: v.number(),
+    })
+        .index("by_hash", ["contactHash"])
+        .index("by_hash_channel", ["contactHash", "channel"]),
+    optInProofs: defineTable({
+        contactHash: v.string(),
+        listKey: v.string(),
+        source: v.string(),
+        proof: v.optional(jsonValue),
+        confirmedAt: v.number(),
+    }).index("by_hash_list", ["contactHash", "listKey"]),
+});
+//# sourceMappingURL=schema.js.map

package/dist/component/schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.js","sourceRoot":"","sources":["../../src/component/schema.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAC1D,OAAO,EAAE,CAAC,EAAE,MAAM,eAAe,CAAC;AAClC,OAAO,EAAE,SAAS,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAE5D;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAe,YAAY,CAAC;IAC1B,YAAY,EAAE,WAAW,CAAC;QACxB,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE;QACvB,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE;QACnB,MAAM,EAAE,iBAAiB;QACzB,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE;KACtB,CAAC;SACC,KAAK,CAAC,SAAS,EAAE,CAAC,aAAa,CAAC,CAAC;SACjC,KAAK,CAAC,iBAAiB,EAAE,CAAC,aAAa,EAAE,SAAS,CAAC,CAAC;IAEvD,WAAW,EAAE,WAAW,CAAC;QACvB,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE;QACvB,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE;QACnB,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE;QAClB,KAAK,EAAE,CAAC,CAAC,QAAQ,CAAC,SAAS,CAAC;QAC5B,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE;KACxB,CAAC,CAAC,KAAK,CAAC,cAAc,EAAE,CAAC,aAAa,EAAE,SAAS,CAAC,CAAC;CACrD,CAAC,CAAC"}

package/dist/component/validators.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Opaque host-owned legal evidence attached to an opt-in proof — e.g. the IP,
+ * user-agent, double-opt-in token ref, or form snapshot the host captured at
+ * confirmation. The component never inspects it; it is last-resort arbitrary data,
+ * aliased here rather than left bare in function signatures. The host narrows it at
+ * the {@link Suppression} client boundary via an optional `proofValidator` parser.
+ *
+ * This is the single documented `v.any()` escape hatch in the component; the lint
+ * rule `convex-rules/no-bare-v-any` is satisfied by routing the arbitrary host
+ * payload through this alias instead of a bare `v.any()`.
+ */
+export declare const jsonValue: import("convex/values").VAny<any, "required", string>;
+/** The five standard reasons a `(contactHash, channel)` is suppressed. */
+export declare const suppressionReason: import("convex/values").VUnion<"unsubscribe" | "bounce" | "complaint" | "manual" | "global", [import("convex/values").VLiteral<"unsubscribe", "required">, import("convex/values").VLiteral<"bounce", "required">, import("convex/values").VLiteral<"complaint", "required">, import("convex/values").VLiteral<"manual", "required">, import("convex/values").VLiteral<"global", "required">], "required", never>;
+/**
+ * Public projection of a suppression returned by {@link isSuppressed}. `channel`
+ * is the host-supplied channel the entry applies to, or `null` for a global
+ * (all-channel) tombstone. `contactHash` is the host's opaque contact hash — never
+ * a raw email/phone.
+ */
+export declare const suppressionView: import("convex/values").VObject<{
+    contactHash: string;
+    channel: string | null;
+    reason: "unsubscribe" | "bounce" | "complaint" | "manual" | "global";
+    createdAt: number;
+}, {
+    contactHash: import("convex/values").VString<string, "required">;
+    channel: import("convex/values").VUnion<string | null, [import("convex/values").VString<string, "required">, import("convex/values").VNull<null, "required">], "required", never>;
+    reason: import("convex/values").VUnion<"unsubscribe" | "bounce" | "complaint" | "manual" | "global", [import("convex/values").VLiteral<"unsubscribe", "required">, import("convex/values").VLiteral<"bounce", "required">, import("convex/values").VLiteral<"complaint", "required">, import("convex/values").VLiteral<"manual", "required">, import("convex/values").VLiteral<"global", "required">], "required", never>;
+    createdAt: import("convex/values").VFloat64<number, "required">;
+}, "required", "contactHash" | "channel" | "reason" | "createdAt">;
+/**
+ * Public projection of an opt-in proof returned by {@link getOptInProof}.
+ * `listKey` scopes the proof to one list/purpose, or `null` for a global opt-in.
+ * `source` tags how the opt-in was captured; `proof` is opaque host evidence.
+ */
+export declare const optInProofView: import("convex/values").VObject<{
+    proof?: any;
+    contactHash: string;
+    listKey: string | null;
+    source: string;
+    confirmedAt: number;
+}, {
+    contactHash: import("convex/values").VString<string, "required">;
+    listKey: import("convex/values").VUnion<string | null, [import("convex/values").VString<string, "required">, import("convex/values").VNull<null, "required">], "required", never>;
+    source: import("convex/values").VString<string, "required">;
+    proof: import("convex/values").VAny<any, "optional", string>;
+    confirmedAt: import("convex/values").VFloat64<number, "required">;
+}, "required", "contactHash" | "listKey" | "source" | "proof" | "confirmedAt" | `proof.${string}`>;
+//# sourceMappingURL=validators.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"validators.d.ts","sourceRoot":"","sources":["../../src/component/validators.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;GAUG;AACH,eAAO,MAAM,SAAS,uDAAU,CAAC;AAEjC,0EAA0E;AAC1E,eAAO,MAAM,iBAAiB,mZAM7B,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,eAAe;;;;;;;;;;kEAK1B,CAAC;AAEH;;;;GAIG;AACH,eAAO,MAAM,cAAc;;;;;;;;;;;;kGAMzB,CAAC"}

package/dist/component/validators.js

@@ -0,0 +1,40 @@
+import { v } from "convex/values";
+/**
+ * Opaque host-owned legal evidence attached to an opt-in proof — e.g. the IP,
+ * user-agent, double-opt-in token ref, or form snapshot the host captured at
+ * confirmation. The component never inspects it; it is last-resort arbitrary data,
+ * aliased here rather than left bare in function signatures. The host narrows it at
+ * the {@link Suppression} client boundary via an optional `proofValidator` parser.
+ *
+ * This is the single documented `v.any()` escape hatch in the component; the lint
+ * rule `convex-rules/no-bare-v-any` is satisfied by routing the arbitrary host
+ * payload through this alias instead of a bare `v.any()`.
+ */
+export const jsonValue = v.any();
+/** The five standard reasons a `(contactHash, channel)` is suppressed. */
+export const suppressionReason = v.union(v.literal("unsubscribe"), v.literal("bounce"), v.literal("complaint"), v.literal("manual"), v.literal("global"));
+/**
+ * Public projection of a suppression returned by {@link isSuppressed}. `channel`
+ * is the host-supplied channel the entry applies to, or `null` for a global
+ * (all-channel) tombstone. `contactHash` is the host's opaque contact hash — never
+ * a raw email/phone.
+ */
+export const suppressionView = v.object({
+    contactHash: v.string(),
+    channel: v.union(v.string(), v.null()),
+    reason: suppressionReason,
+    createdAt: v.number(),
+});
+/**
+ * Public projection of an opt-in proof returned by {@link getOptInProof}.
+ * `listKey` scopes the proof to one list/purpose, or `null` for a global opt-in.
+ * `source` tags how the opt-in was captured; `proof` is opaque host evidence.
+ */
+export const optInProofView = v.object({
+    contactHash: v.string(),
+    listKey: v.union(v.string(), v.null()),
+    source: v.string(),
+    proof: v.optional(jsonValue),
+    confirmedAt: v.number(),
+});
+//# sourceMappingURL=validators.js.map

package/dist/component/validators.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validators.js","sourceRoot":"","sources":["../../src/component/validators.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,eAAe,CAAC;AAElC;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,SAAS,GAAG,CAAC,CAAC,GAAG,EAAE,CAAC;AAEjC,0EAA0E;AAC1E,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CACtC,CAAC,CAAC,OAAO,CAAC,aAAa,CAAC,EACxB,CAAC,CAAC,OAAO,CAAC,QAAQ,CAAC,EACnB,CAAC,CAAC,OAAO,CAAC,WAAW,CAAC,EACtB,CAAC,CAAC,OAAO,CAAC,QAAQ,CAAC,EACnB,CAAC,CAAC,OAAO,CAAC,QAAQ,CAAC,CACpB,CAAC;AAEF;;;;;GAKG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,CAAC,MAAM,CAAC;IACtC,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE;IACvB,OAAO,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;IACtC,MAAM,EAAE,iBAAiB;IACzB,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE;CACtB,CAAC,CAAC;AAEH;;;;GAIG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,CAAC,MAAM,CAAC;IACrC,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE;IACvB,OAAO,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;IACtC,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE;IAClB,KAAK,EAAE,CAAC,CAAC,QAAQ,CAAC,SAAS,CAAC;IAC5B,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE;CACxB,CAAC,CAAC"}

package/dist/shared.d.ts

@@ -0,0 +1,22 @@
+/** Shared constants used by both `client/` and `component/`. */
+export declare const COMPONENT_NAME = "suppression";
+/**
+ * The standard suppression reasons. `unsubscribe` is an explicit opt-out (a
+ * one-click unsubscribe or a list-removal request); `bounce` and `complaint` are
+ * deliverability signals fed from a mail/SMS provider's events; `manual` is an
+ * operator action; `global` marks a do-not-contact-anywhere tombstone. The reason
+ * is recorded for audit — it never changes the suppression's effect (a suppressed
+ * hash is suppressed regardless of why).
+ */
+export declare const SUPPRESSION_REASONS: readonly ["unsubscribe", "bounce", "complaint", "manual", "global"];
+/** A single suppression reason. */
+export type SuppressionReason = (typeof SUPPRESSION_REASONS)[number];
+/**
+ * The sentinel stored in the `channel` index slot for a global (all-channel)
+ * suppression. A real channel is any other host-supplied string (`"email"`,
+ * `"sms"`, `"push"`, …). Storing a concrete value rather than `undefined` lets a
+ * channel-scoped check hit a single equality index that matches the global row and
+ * the channel row in two bounded reads, with no `undefined` index gap.
+ */
+export declare const GLOBAL_CHANNEL = "*";
+//# sourceMappingURL=shared.d.ts.map

package/dist/shared.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shared.d.ts","sourceRoot":"","sources":["../src/shared.ts"],"names":[],"mappings":"AAAA,gEAAgE;AAEhE,eAAO,MAAM,cAAc,gBAAgB,CAAC;AAE5C;;;;;;;GAOG;AACH,eAAO,MAAM,mBAAmB,qEAMtB,CAAC;AAEX,mCAAmC;AACnC,MAAM,MAAM,iBAAiB,GAAG,CAAC,OAAO,mBAAmB,CAAC,CAAC,MAAM,CAAC,CAAC;AAErE;;;;;;GAMG;AACH,eAAO,MAAM,cAAc,MAAM,CAAC"}

package/dist/shared.js

@@ -0,0 +1,26 @@
+/** Shared constants used by both `client/` and `component/`. */
+export const COMPONENT_NAME = "suppression";
+/**
+ * The standard suppression reasons. `unsubscribe` is an explicit opt-out (a
+ * one-click unsubscribe or a list-removal request); `bounce` and `complaint` are
+ * deliverability signals fed from a mail/SMS provider's events; `manual` is an
+ * operator action; `global` marks a do-not-contact-anywhere tombstone. The reason
+ * is recorded for audit — it never changes the suppression's effect (a suppressed
+ * hash is suppressed regardless of why).
+ */
+export const SUPPRESSION_REASONS = [
+    "unsubscribe",
+    "bounce",
+    "complaint",
+    "manual",
+    "global",
+];
+/**
+ * The sentinel stored in the `channel` index slot for a global (all-channel)
+ * suppression. A real channel is any other host-supplied string (`"email"`,
+ * `"sms"`, `"push"`, …). Storing a concrete value rather than `undefined` lets a
+ * channel-scoped check hit a single equality index that matches the global row and
+ * the channel row in two bounded reads, with no `undefined` index gap.
+ */
+export const GLOBAL_CHANNEL = "*";
+//# sourceMappingURL=shared.js.map

package/dist/shared.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"shared.js","sourceRoot":"","sources":["../src/shared.ts"],"names":[],"mappings":"AAAA,gEAAgE;AAEhE,MAAM,CAAC,MAAM,cAAc,GAAG,aAAa,CAAC;AAE5C;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG;IACjC,aAAa;IACb,QAAQ;IACR,WAAW;IACX,QAAQ;IACR,QAAQ;CACA,CAAC;AAKX;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,GAAG,CAAC"}

package/package.json

@@ -0,0 +1,101 @@
+{
+  "name": "@vllnt/convex-suppression",
+  "version": "0.1.0-canary.261f634",
+  "description": "Do-not-contact suppression list + opt-in proof (GDPR/CAN-SPAM), hash-keyed and channel-aware, as a Convex component",
+  "license": "MIT",
+  "type": "module",
+  "packageManager": "pnpm@9.15.4",
+  "files": [
+    "dist",
+    "src"
+  ],
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "types": "./dist/client/index.d.ts",
+      "default": "./dist/client/index.js"
+    },
+    "./test": "./src/test.ts",
+    "./_generated/component.js": {
+      "types": "./dist/component/_generated/component.d.ts"
+    },
+    "./_generated/component": {
+      "types": "./dist/component/_generated/component.d.ts"
+    },
+    "./convex.config": {
+      "types": "./dist/component/convex.config.d.ts",
+      "default": "./dist/component/convex.config.js"
+    },
+    "./convex.config.js": {
+      "types": "./dist/component/convex.config.d.ts",
+      "default": "./dist/component/convex.config.js"
+    }
+  },
+  "types": "./dist/client/index.d.ts",
+  "module": "./dist/client/index.js",
+  "scripts": {
+    "build": "tsc --project ./tsconfig.build.json",
+    "build:codegen": "pnpm convex codegen --component-dir ./src/component && pnpm build",
+    "build:clean": "rm -rf dist *.tsbuildinfo && pnpm build:codegen",
+    "typecheck": "tsc --noEmit",
+    "typecheck:ci": "tsc --noEmit --project tsconfig.ci.json",
+    "lint": "eslint .",
+    "test": "vitest run --passWithNoTests",
+    "test:watch": "vitest --typecheck --clearScreen false",
+    "test:coverage": "vitest run --coverage --coverage.reporter=text",
+    "generate:llms": "node scripts/generate-llms.mjs",
+    "preversion": "pnpm install --frozen-lockfile && pnpm build && pnpm test:coverage && pnpm typecheck && pnpm generate:llms",
+    "prepublishOnly": "npm whoami || npm login",
+    "alpha": "npm version prerelease --preid alpha && npm publish --tag alpha && git push --follow-tags",
+    "release": "npm version patch && npm publish && git push --follow-tags"
+  },
+  "dependencies": {},
+  "peerDependencies": {
+    "convex": "^1.41.0"
+  },
+  "devDependencies": {
+    "@edge-runtime/vm": "^5.0.0",
+    "@vitest/coverage-v8": "^4.1.8",
+    "@vllnt/eslint-config": "^1.0.0",
+    "@vllnt/typescript": "^1.0.0",
+    "convex": "^1.41.0",
+    "convex-test": "^0.0.53",
+    "eslint": "^9.0.0",
+    "prettier": "^3.4.0",
+    "typescript": "^5.7.0",
+    "vitest": "^4.1.8"
+  },
+  "homepage": "https://github.com/vllnt/convex-suppression#readme",
+  "bugs": {
+    "url": "https://github.com/vllnt/convex-suppression/issues"
+  },
+  "author": {
+    "name": "bntvllnt",
+    "url": "https://bntvllnt.com"
+  },
+  "funding": {
+    "type": "github",
+    "url": "https://github.com/sponsors/bntvllnt"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/vllnt/convex-suppression"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "sideEffects": false,
+  "keywords": [
+    "convex",
+    "convex-component",
+    "suppression",
+    "do-not-contact",
+    "unsubscribe",
+    "gdpr",
+    "can-spam",
+    "opt-in"
+  ]
+}