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

package/src/component/_generated/server.ts

@@ -0,0 +1,156 @@
+/* eslint-disable */
+/**
+ * Generated utilities for implementing server-side Convex query and mutation functions.
+ *
+ * THIS CODE IS AUTOMATICALLY GENERATED.
+ *
+ * To regenerate, run `npx convex dev`.
+ * @module
+ */
+
+import type {
+  ActionBuilder,
+  HttpActionBuilder,
+  MutationBuilder,
+  QueryBuilder,
+  GenericActionCtx,
+  GenericMutationCtx,
+  GenericQueryCtx,
+  GenericDatabaseReader,
+  GenericDatabaseWriter,
+} from "convex/server";
+import {
+  actionGeneric,
+  httpActionGeneric,
+  queryGeneric,
+  mutationGeneric,
+  internalActionGeneric,
+  internalMutationGeneric,
+  internalQueryGeneric,
+} from "convex/server";
+import type { DataModel } from "./dataModel.js";
+
+/**
+ * Define a query in this Convex app's public API.
+ *
+ * This function will be allowed to read your Convex database and will be accessible from the client.
+ *
+ * @param func - The query function. It receives a {@link QueryCtx} as its first argument.
+ * @returns The wrapped query. Include this as an `export` to name it and make it accessible.
+ */
+export const query: QueryBuilder<DataModel, "public"> = queryGeneric;
+
+/**
+ * Define a query that is only accessible from other Convex functions (but not from the client).
+ *
+ * This function will be allowed to read from your Convex database. It will not be accessible from the client.
+ *
+ * @param func - The query function. It receives a {@link QueryCtx} as its first argument.
+ * @returns The wrapped query. Include this as an `export` to name it and make it accessible.
+ */
+export const internalQuery: QueryBuilder<DataModel, "internal"> =
+  internalQueryGeneric;
+
+/**
+ * Define a mutation in this Convex app's public API.
+ *
+ * This function will be allowed to modify your Convex database and will be accessible from the client.
+ *
+ * @param func - The mutation function. It receives a {@link MutationCtx} as its first argument.
+ * @returns The wrapped mutation. Include this as an `export` to name it and make it accessible.
+ */
+export const mutation: MutationBuilder<DataModel, "public"> = mutationGeneric;
+
+/**
+ * Define a mutation that is only accessible from other Convex functions (but not from the client).
+ *
+ * This function will be allowed to modify your Convex database. It will not be accessible from the client.
+ *
+ * @param func - The mutation function. It receives a {@link MutationCtx} as its first argument.
+ * @returns The wrapped mutation. Include this as an `export` to name it and make it accessible.
+ */
+export const internalMutation: MutationBuilder<DataModel, "internal"> =
+  internalMutationGeneric;
+
+/**
+ * Define an action in this Convex app's public API.
+ *
+ * An action is a function which can execute any JavaScript code, including non-deterministic
+ * code and code with side-effects, like calling third-party services.
+ * They can be run in Convex's JavaScript environment or in Node.js using the "use node" directive.
+ * They can interact with the database indirectly by calling queries and mutations using the {@link ActionCtx}.
+ *
+ * @param func - The action. It receives an {@link ActionCtx} as its first argument.
+ * @returns The wrapped action. Include this as an `export` to name it and make it accessible.
+ */
+export const action: ActionBuilder<DataModel, "public"> = actionGeneric;
+
+/**
+ * Define an action that is only accessible from other Convex functions (but not from the client).
+ *
+ * @param func - The function. It receives an {@link ActionCtx} as its first argument.
+ * @returns The wrapped function. Include this as an `export` to name it and make it accessible.
+ */
+export const internalAction: ActionBuilder<DataModel, "internal"> =
+  internalActionGeneric;
+
+/**
+ * Define an HTTP action.
+ *
+ * The wrapped function will be used to respond to HTTP requests received
+ * by a Convex deployment if the requests matches the path and method where
+ * this action is routed. Be sure to route your httpAction in `convex/http.js`.
+ *
+ * @param func - The function. It receives an {@link ActionCtx} as its first argument
+ * and a Fetch API `Request` object as its second.
+ * @returns The wrapped function. Import this function from `convex/http.js` and route it to hook it up.
+ */
+export const httpAction: HttpActionBuilder = httpActionGeneric;
+
+/**
+ * A set of services for use within Convex query functions.
+ *
+ * The query context is passed as the first argument to any Convex query
+ * function run on the server.
+ *
+ * If you're using code generation, use the `QueryCtx` type in `convex/_generated/server.d.ts` instead.
+ */
+export type QueryCtx = GenericQueryCtx<DataModel>;
+
+/**
+ * A set of services for use within Convex mutation functions.
+ *
+ * The mutation context is passed as the first argument to any Convex mutation
+ * function run on the server.
+ *
+ * If you're using code generation, use the `MutationCtx` type in `convex/_generated/server.d.ts` instead.
+ */
+export type MutationCtx = GenericMutationCtx<DataModel>;
+
+/**
+ * A set of services for use within Convex action functions.
+ *
+ * The action context is passed as the first argument to any Convex action
+ * function run on the server.
+ */
+export type ActionCtx = GenericActionCtx<DataModel>;
+
+/**
+ * An interface to read from the database within Convex query functions.
+ *
+ * The two entry points are {@link DatabaseReader.get}, which fetches a single
+ * document by its {@link Id}, or {@link DatabaseReader.query}, which starts
+ * building a query.
+ */
+export type DatabaseReader = GenericDatabaseReader<DataModel>;
+
+/**
+ * An interface to read from and write to the database within Convex mutation
+ * functions.
+ *
+ * Convex guarantees that all writes within a single mutation are
+ * executed atomically, so you never have to worry about partial writes leaving
+ * your data in an inconsistent state. See [the Convex Guide](https://docs.convex.dev/understanding/convex-fundamentals/functions#atomicity-and-optimistic-concurrency-control)
+ * for the guarantees Convex provides your functions.
+ */
+export type DatabaseWriter = GenericDatabaseWriter<DataModel>;

package/src/component/convex.config.ts

@@ -0,0 +1,9 @@
+import { defineComponent } from "convex/server";
+
+const component = defineComponent("suppression");
+
+// Nest official child components here, e.g.:
+// import sharded from "@convex-dev/sharded-counter/convex.config";
+// component.use(sharded);
+
+export default component;

package/src/component/mutations.ts

@@ -0,0 +1,118 @@
+import { v } from "convex/values";
+import { mutation } from "./_generated/server";
+import { jsonValue, suppressionReason } from "./validators";
+
+/**
+ * Suppress a `(contactHash, channel)` — add it to the do-not-contact list. The
+ * host hashes and normalizes the contact itself and passes the opaque
+ * `contactHash`; the component never sees a raw email/phone, so the entry survives
+ * erasure of the underlying subject. `channel` is the host channel string
+ * (`"email"`/`"sms"`/`"push"`/…) the suppression applies to; omit it for a global
+ * (all-channel) suppression. `reason` is recorded for audit.
+ *
+ * Idempotent on `(contactHash, channel)`: re-suppressing an existing entry updates
+ * its `reason` and refreshes `createdAt` rather than inserting a duplicate, so a
+ * replayed bounce/complaint webhook can never fan the table out. `createdAt` is
+ * stamped from the server clock (`Date.now()` inside the handler — never
+ * caller-supplied).
+ */
+export const suppress = mutation({
+  args: {
+    contactHash: v.string(),
+    channel: v.string(),
+    reason: suppressionReason,
+  },
+  returns: v.null(),
+  handler: async (ctx, args) => {
+    const existing = await ctx.db
+      .query("suppressions")
+      .withIndex("by_hash_channel", (q) =>
+        q.eq("contactHash", args.contactHash).eq("channel", args.channel),
+      )
+      .unique();
+    const now = Date.now();
+    if (existing !== null) {
+      await ctx.db.patch(existing._id, { reason: args.reason, createdAt: now });
+      return null;
+    }
+    await ctx.db.insert("suppressions", {
+      contactHash: args.contactHash,
+      channel: args.channel,
+      reason: args.reason,
+      createdAt: now,
+    });
+    return null;
+  },
+});
+
+/**
+ * Remove a `(contactHash, channel)` from the do-not-contact list — a rare, audited
+ * re-subscribe. Removing a global suppression (`channel` = the sentinel) clears
+ * only the global row, not per-channel entries; removing a channel row clears only
+ * that channel. Returns `true` if an entry was removed, `false` if none matched (a
+ * no-op unsuppress of an address that was never suppressed is not an error).
+ */
+export const unsuppress = mutation({
+  args: { contactHash: v.string(), channel: v.string() },
+  returns: v.boolean(),
+  handler: async (ctx, args) => {
+    const existing = await ctx.db
+      .query("suppressions")
+      .withIndex("by_hash_channel", (q) =>
+        q.eq("contactHash", args.contactHash).eq("channel", args.channel),
+      )
+      .unique();
+    if (existing === null) {
+      return false;
+    }
+    await ctx.db.delete(existing._id);
+    return true;
+  },
+});
+
+/**
+ * Record an opt-in proof for a `(contactHash, listKey)` — the legal evidence that
+ * this contact confirmed receiving mail/messages for one list/purpose (a double
+ * opt-in, an explicit checkbox, an import with consent). `listKey` scopes the
+ * proof to one list or holds the global sentinel; `source` tags how it was
+ * captured; `proof` is opaque host evidence (IP, token ref, form snapshot) narrowed
+ * by the host's validator at the client boundary.
+ *
+ * Idempotent on `(contactHash, listKey)`: a second confirmation updates `source`,
+ * `proof`, and `confirmedAt` rather than inserting a duplicate. `confirmedAt` is
+ * server-sourced.
+ */
+export const recordOptIn = mutation({
+  args: {
+    contactHash: v.string(),
+    listKey: v.string(),
+    source: v.string(),
+    proof: v.optional(jsonValue),
+  },
+  returns: v.null(),
+  handler: async (ctx, args) => {
+    const existing = await ctx.db
+      .query("optInProofs")
+      .withIndex("by_hash_list", (q) =>
+        q.eq("contactHash", args.contactHash).eq("listKey", args.listKey),
+      )
+      .unique();
+    const now = Date.now();
+    if (existing !== null) {
+      await ctx.db.patch(existing._id, {
+        source: args.source,
+        proof: args.proof,
+        confirmedAt: now,
+      });
+      return null;
+    }
+    await ctx.db.insert("optInProofs", {
+      contactHash: args.contactHash,
+      listKey: args.listKey,
+      source: args.source,
+      proof: args.proof,
+      confirmedAt: now,
+    });
+    return null;
+  },
+});

package/src/component/queries.ts

@@ -0,0 +1,128 @@
+import { v } from "convex/values";
+import { query } from "./_generated/server";
+import { GLOBAL_CHANNEL } from "../shared";
+import { optInProofView, suppressionView } from "./validators";
+import type { Doc } from "./_generated/dataModel";
+
+/** Project a stored suppression row to its public view (drops internal fields). */
+function view(row: Doc<"suppressions">) {
+  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;
+  },
+});

package/src/component/schema.ts

@@ -0,0 +1,40 @@
+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"]),
+});

package/src/component/validators.ts

@@ -0,0 +1,49 @@
+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(),
+});

package/src/shared.ts

@@ -0,0 +1,31 @@
+/** 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",
+] as const;
+
+/** 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 const GLOBAL_CHANNEL = "*";

package/src/test.ts

@@ -0,0 +1,15 @@
+import type { TestConvex } from "convex-test";
+import schema from "./component/schema";
+
+const modules = import.meta.glob("./component/**/*.ts");
+
+/**
+ * Register this component with a `convex-test` instance so consuming apps can
+ * test integration: `import { register } from "@vllnt/convex-suppression/test"`.
+ */
+export function register(
+  t: TestConvex<typeof schema>,
+  name = "suppression",
+): void {
+  t.registerComponent(name, schema, modules);
+}