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

package/src/client/index.ts

@@ -0,0 +1,271 @@
+import type {
+  FunctionArgs,
+  FunctionReference,
+  FunctionReturnType,
+} from "convex/server";
+import type {
+  IsEligibleOptions,
+  OptInProofView,
+  Parser,
+  RecordOptInOptions,
+  SuppressionOptions,
+  SuppressionReason,
+  SuppressionView,
+  SuppressOptions,
+} from "./types.js";
+import { GLOBAL_CHANNEL } from "../shared.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 class Suppression<TProof = unknown> {
+  private readonly proofValidator: Parser<TProof> | undefined;
+
+  constructor(
+    private readonly component: SuppressionComponent,
+    options: SuppressionOptions<TProof> = {},
+  ) {
+    this.proofValidator = options.proofValidator;
+  }
+
+  /** Narrow an opaque value through a host parser; pass `undefined` and unset parsers through. */
+  private parse(value: unknown): TProof | undefined {
+    if (value === undefined) {
+      return undefined;
+    }
+    if (this.proofValidator === undefined) {
+      return value as TProof;
+    }
+    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: RunMutationCtx,
+    contactHash: string,
+    reason: SuppressionReason,
+    opts: SuppressOptions = {},
+  ): Promise<null> {
+    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: RunMutationCtx,
+    contactHash: string,
+    channel?: string,
+  ): Promise<boolean> {
+    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: RunQueryCtx,
+    contactHash: string,
+    channel?: string,
+  ): Promise<SuppressionView | null> {
+    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: RunMutationCtx,
+    contactHash: string,
+    opts: RecordOptInOptions<TProof>,
+  ): Promise<null> {
+    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: RunQueryCtx,
+    contactHash: string,
+    listKey?: string,
+  ): Promise<OptInProofView<TProof> | null> {
+    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: RunQueryCtx,
+    contactHash: string,
+    opts: IsEligibleOptions = {},
+  ): Promise<boolean> {
+    return ctx.runQuery(this.component.queries.isEligible, {
+      contactHash,
+      channel: opts.channel ?? GLOBAL_CHANNEL,
+      listKey: opts.listKey ?? GLOBAL_CHANNEL,
+      requireOptIn: opts.requireOptIn ?? false,
+    });
+  }
+}
+
+export type {
+  IsEligibleOptions,
+  OptInProofView,
+  Parser,
+  RecordOptInOptions,
+  SuppressionOptions,
+  SuppressionReason,
+  SuppressionView,
+  SuppressOptions,
+};

package/src/client/types.ts

@@ -0,0 +1,82 @@
+/** 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>;
+}

package/src/component/_generated/api.ts

@@ -0,0 +1,54 @@
+/* eslint-disable */
+/**
+ * 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";
+import { anyApi, componentsGeneric } from "convex/server";
+
+const fullApi: ApiFromModules<{
+  mutations: typeof mutations;
+  queries: typeof queries;
+  validators: typeof validators;
+}> = anyApi as any;
+
+/**
+ * A utility for referencing Convex functions in your app's public API.
+ *
+ * Usage:
+ * ```js
+ * const myFunctionReference = api.myModule.myFunction;
+ * ```
+ */
+export const api: FilterApi<
+  typeof fullApi,
+  FunctionReference<any, "public">
+> = anyApi as any;
+
+/**
+ * A utility for referencing Convex functions in your app's internal API.
+ *
+ * Usage:
+ * ```js
+ * const myFunctionReference = internal.myModule.myFunction;
+ * ```
+ */
+export const internal: FilterApi<
+  typeof fullApi,
+  FunctionReference<any, "internal">
+> = anyApi as any;
+
+export const components = componentsGeneric() as unknown as {};

package/src/component/_generated/component.ts

@@ -0,0 +1,102 @@
+/* eslint-disable */
+/**
+ * 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: {
+      suppress: FunctionReference<
+        "mutation",
+        "internal",
+        {
+          channel: string;
+          contactHash: string;
+          reason:
+            | "unsubscribe"
+            | "bounce"
+            | "complaint"
+            | "manual"
+            | "global";
+        },
+        null,
+        Name
+      >;
+      unsuppress: FunctionReference<
+        "mutation",
+        "internal",
+        { channel: string; contactHash: string },
+        boolean,
+        Name
+      >;
+      recordOptIn: FunctionReference<
+        "mutation",
+        "internal",
+        { contactHash: string; listKey: string; proof?: any; source: string },
+        null,
+        Name
+      >;
+    };
+    queries: {
+      isSuppressed: FunctionReference<
+        "query",
+        "internal",
+        { channel: string; contactHash: string },
+        null | {
+          channel: string | null;
+          contactHash: string;
+          createdAt: number;
+          reason:
+            | "unsubscribe"
+            | "bounce"
+            | "complaint"
+            | "manual"
+            | "global";
+        },
+        Name
+      >;
+      getOptInProof: FunctionReference<
+        "query",
+        "internal",
+        { contactHash: string; listKey: string },
+        null | {
+          confirmedAt: number;
+          contactHash: string;
+          listKey: string | null;
+          proof?: any;
+          source: string;
+        },
+        Name
+      >;
+      isEligible: FunctionReference<
+        "query",
+        "internal",
+        {
+          channel: string;
+          contactHash: string;
+          listKey: string;
+          requireOptIn: boolean;
+        },
+        boolean,
+        Name
+      >;
+    };
+  };

package/src/component/_generated/dataModel.ts

@@ -0,0 +1,60 @@
+/* eslint-disable */
+/**
+ * Generated data model types.
+ *
+ * THIS CODE IS AUTOMATICALLY GENERATED.
+ *
+ * To regenerate, run `npx convex dev`.
+ * @module
+ */
+
+import type {
+  DataModelFromSchemaDefinition,
+  DocumentByName,
+  TableNamesInDataModel,
+  SystemTableNames,
+} from "convex/server";
+import type { GenericId } from "convex/values";
+import schema from "../schema.js";
+
+/**
+ * The names of all of your Convex tables.
+ */
+export type TableNames = TableNamesInDataModel<DataModel>;
+
+/**
+ * The type of a document stored in Convex.
+ *
+ * @typeParam TableName - A string literal type of the table name (like "users").
+ */
+export type Doc<TableName extends TableNames> = DocumentByName<
+  DataModel,
+  TableName
+>;
+
+/**
+ * An identifier for a document in Convex.
+ *
+ * Convex documents are uniquely identified by their `Id`, which is accessible
+ * on the `_id` field. To learn more, see [Document IDs](https://docs.convex.dev/using/document-ids).
+ *
+ * Documents can be loaded using `db.get(tableName, id)` in query and mutation functions.
+ *
+ * IDs are just strings at runtime, but this type can be used to distinguish them from other
+ * strings when type checking.
+ *
+ * @typeParam TableName - A string literal type of the table name (like "users").
+ */
+export type Id<TableName extends TableNames | SystemTableNames> =
+  GenericId<TableName>;
+
+/**
+ * A type describing your Convex data model.
+ *
+ * This type includes information about what tables you have, the type of
+ * documents stored in those tables, and the indexes defined on them.
+ *
+ * This type is used to parameterize methods like `queryGeneric` and
+ * `mutationGeneric` to make them type-safe.
+ */
+export type DataModel = DataModelFromSchemaDefinition<typeof schema>;