@robelest/convex-auth 0.0.4-preview.25 → 0.0.4-preview.28

package/src/component/public/enterprise/core.ts

@@ -1,355 +0,0 @@
-import { ConvexError, v } from "convex/values";
-
-import { mutation, query } from "../../functions";
-import {
-  vEnterpriseDoc,
-  vEnterpriseDomainDoc,
-  vEnterprisePolicy,
-  vEnterpriseStatus,
-  vPaginated,
-} from "../../model";
-
-/**
- * Create a new enterprise record attached to a root group.
- *
- * Each group may only have one enterprise record. If an enterprise already
- * exists for the given group, a `ENTERPRISE_ALREADY_EXISTS` error is thrown.
- * The enterprise status defaults to `"draft"` when not explicitly provided.
- *
- * @param args.groupId - The ID of the root group that owns this enterprise.
- * @param args.slug - An optional URL-friendly identifier for the enterprise.
- * @param args.name - An optional human-readable display name for the enterprise.
- * @param args.status - The lifecycle status (`"draft"`, `"active"`, or `"disabled"`). Defaults to `"draft"`.
- * @param args.policy - An optional enterprise policy object controlling identity linking, provisioning, and deprovisioning behavior.
- * @param args.config - An optional arbitrary configuration blob for enterprise-specific settings.
- * @param args.extend - An optional arbitrary extension object for custom fields.
- * @returns The ID of the newly created `Enterprise` document.
- *
- * @example
- * ```ts
- * const enterpriseId = await ctx.runMutation(
- *   components.auth.enterprise.enterpriseCreate,
- *   {
- *     groupId: orgGroupId,
- *     slug: "acme-corp",
- *     name: "Acme Corporation",
- *     status: "active",
- *   },
- * );
- * ```
- */
-export const enterpriseCreate = mutation({
-  args: {
-    groupId: v.id("Group"),
-    slug: v.optional(v.string()),
-    name: v.optional(v.string()),
-    status: v.optional(vEnterpriseStatus),
-    policy: v.optional(vEnterprisePolicy),
-    config: v.optional(v.any()),
-    extend: v.optional(v.any()),
-  },
-  returns: v.id("Enterprise"),
-  handler: async (ctx, args) => {
-    const existing = await ctx.db
-      .query("Enterprise")
-      .withIndex("group_id", (idx) => idx.eq("groupId", args.groupId))
-      .first();
-    if (existing) {
-      throw new ConvexError({
-        code: "ENTERPRISE_ALREADY_EXISTS",
-        message: "An enterprise record already exists for this group.",
-      });
-    }
-    return await ctx.db.insert("Enterprise", {
-      ...args,
-      status: args.status ?? "draft",
-    });
-  },
-});
-
-/**
- * Retrieve a single enterprise record by its document ID.
- *
- * Returns the full enterprise document if it exists, or `null` if no
- * enterprise is found with the given ID.
- *
- * @param args.enterpriseId - The document ID of the enterprise to retrieve.
- * @returns The enterprise document, or `null` if not found.
- *
- * @example
- * ```ts
- * const enterprise = await ctx.runQuery(
- *   components.auth.enterprise.enterpriseGet,
- *   { enterpriseId },
- * );
- * if (enterprise) {
- *   console.log(enterprise.name, enterprise.status);
- * }
- * ```
- */
-export const enterpriseGet = query({
-  args: { enterpriseId: v.id("Enterprise") },
-  returns: v.union(vEnterpriseDoc, v.null()),
-  handler: async (ctx, { enterpriseId }) => {
-    return await ctx.db.get("Enterprise", enterpriseId);
-  },
-});
-
-/**
- * Retrieve an enterprise record by the ID of its owning group.
- *
- * Looks up the enterprise that is linked to the specified group using the
- * `group_id` index. Returns `null` if no enterprise is associated with the group.
- *
- * @param args.groupId - The ID of the root group whose enterprise record to look up.
- * @returns The enterprise document, or `null` if the group has no enterprise.
- *
- * @example
- * ```ts
- * const enterprise = await ctx.runQuery(
- *   components.auth.enterprise.enterpriseGetByGroup,
- *   { groupId: orgGroupId },
- * );
- * ```
- */
-export const enterpriseGetByGroup = query({
-  args: { groupId: v.id("Group") },
-  returns: v.union(vEnterpriseDoc, v.null()),
-  handler: async (ctx, { groupId }) => {
-    return await ctx.db
-      .query("Enterprise")
-      .withIndex("group_id", (idx) => idx.eq("groupId", groupId))
-      .first();
-  },
-});
-
-/**
- * Retrieve an enterprise record by one of its linked domain names.
- *
- * Looks up an `EnterpriseDomain` row matching the given domain string, then
- * resolves the parent enterprise. Returns both the enterprise and the matched
- * domain document, or `null` if the domain is not registered or its enterprise
- * no longer exists.
- *
- * @param args.domain - The domain name to search for (e.g. `"acme.com"`).
- * @returns An object containing the `enterprise` and `domain` documents, or `null` if not found.
- *
- * @example
- * ```ts
- * const result = await ctx.runQuery(
- *   components.auth.enterprise.enterpriseGetByDomain,
- *   { domain: "acme.com" },
- * );
- * if (result) {
- *   console.log(result.enterprise.name, result.domain.verifiedAt);
- * }
- * ```
- */
-export const enterpriseGetByDomain = query({
-  args: { domain: v.string() },
-  returns: v.union(
-    v.object({
-      enterprise: vEnterpriseDoc,
-      domain: vEnterpriseDomainDoc,
-    }),
-    v.null(),
-  ),
-  handler: async (ctx, { domain }) => {
-    const domainRow = await ctx.db
-      .query("EnterpriseDomain")
-      .withIndex("domain", (idx) => idx.eq("domain", domain))
-      .first();
-    if (!domainRow) {
-      return null;
-    }
-    const enterprise = await ctx.db.get("Enterprise", domainRow.enterpriseId);
-    if (!enterprise) {
-      return null;
-    }
-    return { enterprise, domain: domainRow };
-  },
-});
-
-/**
- * List enterprise records with optional filtering and cursor-based pagination.
- *
- * Supports filtering by `groupId`, `slug`, and/or `status`. The query selects
- * the most specific index available for the primary filter, then applies
- * remaining predicates as post-filters. Results are ordered by creation time
- * (or the specified field) and paginated using an opaque cursor.
- *
- * @param args.where - Optional filter criteria: `groupId`, `slug`, and/or `status`.
- * @param args.limit - Maximum number of items per page (clamped between 1 and 100, defaults to 50).
- * @param args.cursor - An opaque cursor string returned from a previous call to fetch the next page, or `null` / omitted for the first page.
- * @param args.orderBy - The field to sort results by: `"_creationTime"`, `"name"`, `"slug"`, or `"status"`.
- * @param args.order - Sort direction: `"asc"` or `"desc"` (defaults to `"desc"`).
- * @returns A paginated result containing `items` (array of enterprise documents) and `nextCursor` (`string | null`).
- *
- * @example
- * ```ts
- * const page = await ctx.runQuery(
- *   components.auth.enterprise.enterpriseList,
- *   {
- *     where: { status: "active" },
- *     limit: 25,
- *     order: "asc",
- *   },
- * );
- * for (const ent of page.items) {
- *   console.log(ent.name);
- * }
- * // Fetch next page:
- * const nextPage = await ctx.runQuery(
- *   components.auth.enterprise.enterpriseList,
- *   { where: { status: "active" }, cursor: page.nextCursor },
- * );
- * ```
- */
-export const enterpriseList = query({
-  args: {
-    where: v.optional(
-      v.object({
-        groupId: v.optional(v.id("Group")),
-        slug: v.optional(v.string()),
-        status: v.optional(vEnterpriseStatus),
-      }),
-    ),
-    limit: v.optional(v.number()),
-    cursor: v.optional(v.union(v.string(), v.null())),
-    orderBy: v.optional(
-      v.union(
-        v.literal("_creationTime"),
-        v.literal("name"),
-        v.literal("slug"),
-        v.literal("status"),
-      ),
-    ),
-    order: v.optional(v.union(v.literal("asc"), v.literal("desc"))),
-  },
-  returns: vPaginated(vEnterpriseDoc),
-  handler: async (ctx, args) => {
-    const where = args.where ?? {};
-    const limit = Math.min(Math.max(args.limit ?? 50, 1), 100);
-    const order = args.order ?? "desc";
-
-    let q;
-    if (where.groupId !== undefined) {
-      q = ctx.db
-        .query("Enterprise")
-        .withIndex("group_id", (idx) => idx.eq("groupId", where.groupId!));
-    } else if (where.slug !== undefined) {
-      q = ctx.db
-        .query("Enterprise")
-        .withIndex("slug", (idx) => idx.eq("slug", where.slug!));
-    } else if (where.status !== undefined) {
-      q = ctx.db
-        .query("Enterprise")
-        .withIndex("status", (idx) => idx.eq("status", where.status!));
-    } else {
-      q = ctx.db.query("Enterprise");
-    }
-
-    if (where.groupId !== undefined && where.slug !== undefined) {
-      q = q.filter((f) => f.eq(f.field("slug"), where.slug!));
-    }
-    if (where.status !== undefined && where.groupId === undefined) {
-      // already handled by index in the dedicated branch
-    } else if (where.status !== undefined) {
-      q = q.filter((f) => f.eq(f.field("status"), where.status!));
-    }
-
-    q = q.order(order);
-    const all = await q.collect();
-    let startIdx = 0;
-    if (args.cursor) {
-      const cursorIdx = all.findIndex((doc) => doc._id === args.cursor);
-      if (cursorIdx !== -1) {
-        startIdx = cursorIdx + 1;
-      }
-    }
-    const page = all.slice(startIdx, startIdx + limit + 1);
-    const hasMore = page.length > limit;
-    const items = hasMore ? page.slice(0, limit) : page;
-    const nextCursor = hasMore ? items[items.length - 1]._id : null;
-    return { items, nextCursor };
-  },
-});
-
-/**
- * Partially update (patch) an existing enterprise record.
- *
- * Merges the provided `data` fields into the existing enterprise document.
- * Only the fields present in `data` are changed; all other fields are preserved.
- *
- * @param args.enterpriseId - The document ID of the enterprise to update.
- * @param args.data - An object containing the fields to update (e.g. `{ name, status, policy }`).
- * @returns `null` on success.
- *
- * @example
- * ```ts
- * await ctx.runMutation(
- *   components.auth.enterprise.enterpriseUpdate,
- *   {
- *     enterpriseId,
- *     data: { status: "active", name: "Acme Corp (Renamed)" },
- *   },
- * );
- * ```
- */
-export const enterpriseUpdate = mutation({
-  args: { enterpriseId: v.id("Enterprise"), data: v.any() },
-  returns: v.null(),
-  handler: async (ctx, { enterpriseId, data }) => {
-    await ctx.db.patch(enterpriseId, data);
-    return null;
-  },
-});
-
-/**
- * Delete an enterprise record and all of its associated child data.
- *
- * This cascading delete removes the enterprise document along with all linked
- * domain records, domain verification records, and enterprise secrets. Callers
- * should ensure that higher-level cleanup (e.g. SCIM identities, webhook
- * endpoints) is handled separately if needed.
- *
- * @param args.enterpriseId - The document ID of the enterprise to delete.
- * @returns `null` on success.
- *
- * @example
- * ```ts
- * await ctx.runMutation(
- *   components.auth.enterprise.enterpriseDelete,
- *   { enterpriseId },
- * );
- * ```
- */
-export const enterpriseDelete = mutation({
-  args: { enterpriseId: v.id("Enterprise") },
-  returns: v.null(),
-  handler: async (ctx, { enterpriseId }) => {
-    const domains = await ctx.db
-      .query("EnterpriseDomain")
-      .withIndex("enterprise_id", (idx) => idx.eq("enterpriseId", enterpriseId))
-      .collect();
-    for (const domain of domains) {
-      const verification = await ctx.db
-        .query("EnterpriseDomainVerification")
-        .withIndex("domain_id", (idx) => idx.eq("domainId", domain._id))
-        .first();
-      if (verification) {
-        await ctx.db.delete(verification._id);
-      }
-      await ctx.db.delete(domain._id);
-    }
-    const secrets = await ctx.db
-      .query("EnterpriseSecret")
-      .withIndex("enterprise_id", (idx) => idx.eq("enterpriseId", enterpriseId))
-      .collect();
-    for (const secret of secrets) {
-      await ctx.db.delete(secret._id);
-    }
-    await ctx.db.delete(enterpriseId);
-    return null;
-  },
-});

package/src/component/public/enterprise/domains.ts

@@ -1,327 +0,0 @@
-import { ConvexError, v } from "convex/values";
-
-import { mutation, query } from "../../functions";
-import {
-  vEnterpriseDomainDoc,
-  vEnterpriseDomainVerificationDoc,
-} from "../../model";
-
-/**
- * Link a domain to an enterprise record, or update an existing link.
- *
- * If the domain is already attached to a different enterprise, an
- * `ENTERPRISE_DOMAIN_TAKEN` error is thrown. If the domain already exists for
- * this enterprise, it is updated in place (e.g. toggling `isPrimary`). When
- * `isPrimary` is `true`, any previously primary domain on the same enterprise
- * is demoted. The first domain added to an enterprise becomes primary by default.
- *
- * @param args.enterpriseId - The ID of the enterprise to attach the domain to.
- * @param args.groupId - The ID of the root group that owns the enterprise.
- * @param args.domain - The domain name to link (e.g. `"acme.com"`).
- * @param args.isPrimary - Whether this domain should be set as the primary domain for the enterprise. Defaults to `true` for the first domain.
- * @returns The ID of the created or updated `EnterpriseDomain` document.
- *
- * @example
- * ```ts
- * const domainId = await ctx.runMutation(
- *   components.auth.enterprise.enterpriseDomainAdd,
- *   {
- *     enterpriseId,
- *     groupId: orgGroupId,
- *     domain: "acme.com",
- *     isPrimary: true,
- *   },
- * );
- * ```
- */
-export const enterpriseDomainAdd = mutation({
-  args: {
-    enterpriseId: v.id("Enterprise"),
-    groupId: v.id("Group"),
-    domain: v.string(),
-    isPrimary: v.optional(v.boolean()),
-  },
-  returns: v.id("EnterpriseDomain"),
-  handler: async (ctx, args) => {
-    const existingByDomain = await ctx.db
-      .query("EnterpriseDomain")
-      .withIndex("domain", (idx) => idx.eq("domain", args.domain))
-      .first();
-    if (
-      existingByDomain &&
-      existingByDomain.enterpriseId !== args.enterpriseId
-    ) {
-      throw new ConvexError({
-        code: "ENTERPRISE_DOMAIN_TAKEN",
-        message: "That domain is already attached to another enterprise.",
-      });
-    }
-
-    const existingForEnterprise = await ctx.db
-      .query("EnterpriseDomain")
-      .withIndex("enterprise_id", (idx) =>
-        idx.eq("enterpriseId", args.enterpriseId),
-      )
-      .collect();
-
-    for (const row of existingForEnterprise) {
-      if (row.domain === args.domain) {
-        await ctx.db.patch(row._id, {
-          isPrimary: args.isPrimary ?? row.isPrimary,
-        });
-        return row._id;
-      }
-    }
-
-    if (args.isPrimary === true) {
-      for (const row of existingForEnterprise) {
-        if (row.isPrimary) {
-          await ctx.db.patch(row._id, { isPrimary: false });
-        }
-      }
-    }
-
-    return await ctx.db.insert("EnterpriseDomain", {
-      ...args,
-      isPrimary: args.isPrimary ?? existingForEnterprise.length === 0,
-    });
-  },
-});
-
-/**
- * List all domains linked to a specific enterprise.
- *
- * Returns all `EnterpriseDomain` documents associated with the given enterprise,
- * queried via the `enterprise_id` index. The result includes both verified and
- * unverified domains.
- *
- * @param args.enterpriseId - The ID of the enterprise whose domains to list.
- * @returns An array of enterprise domain documents.
- *
- * @example
- * ```ts
- * const domains = await ctx.runQuery(
- *   components.auth.enterprise.enterpriseDomainList,
- *   { enterpriseId },
- * );
- * for (const d of domains) {
- *   console.log(d.domain, d.isPrimary, d.verifiedAt);
- * }
- * ```
- */
-export const enterpriseDomainList = query({
-  args: { enterpriseId: v.id("Enterprise") },
-  returns: v.array(vEnterpriseDomainDoc),
-  handler: async (ctx, { enterpriseId }) => {
-    return await ctx.db
-      .query("EnterpriseDomain")
-      .withIndex("enterprise_id", (idx) => idx.eq("enterpriseId", enterpriseId))
-      .collect();
-  },
-});
-
-/**
- * Remove a linked enterprise domain and its associated verification record.
- *
- * Deletes the `EnterpriseDomain` document and, if one exists, the related
- * `EnterpriseDomainVerification` record. This is a permanent deletion.
- *
- * @param args.domainId - The document ID of the enterprise domain to remove.
- * @returns `null` on success.
- *
- * @example
- * ```ts
- * await ctx.runMutation(
- *   components.auth.enterprise.enterpriseDomainDelete,
- *   { domainId },
- * );
- * ```
- */
-export const enterpriseDomainDelete = mutation({
-  args: { domainId: v.id("EnterpriseDomain") },
-  returns: v.null(),
-  handler: async (ctx, { domainId }) => {
-    const verification = await ctx.db
-      .query("EnterpriseDomainVerification")
-      .withIndex("domain_id", (idx) => idx.eq("domainId", domainId))
-      .first();
-    if (verification) {
-      await ctx.db.delete(verification._id);
-    }
-    await ctx.db.delete(domainId);
-    return null;
-  },
-});
-
-/**
- * Retrieve the pending domain verification record for a given enterprise domain.
- *
- * Returns the `EnterpriseDomainVerification` document associated with the
- * specified domain, or `null` if no verification has been initiated.
- *
- * @param args.domainId - The document ID of the enterprise domain whose verification to retrieve.
- * @returns The domain verification document, or `null` if none exists.
- *
- * @example
- * ```ts
- * const verification = await ctx.runQuery(
- *   components.auth.enterprise.enterpriseDomainVerificationGet,
- *   { domainId },
- * );
- * if (verification) {
- *   console.log(verification.recordName, verification.expiresAt);
- * }
- * ```
- */
-export const enterpriseDomainVerificationGet = query({
-  args: { domainId: v.id("EnterpriseDomain") },
-  returns: v.union(vEnterpriseDomainVerificationDoc, v.null()),
-  handler: async (ctx, { domainId }) => {
-    return await ctx.db
-      .query("EnterpriseDomainVerification")
-      .withIndex("domain_id", (idx) => idx.eq("domainId", domainId))
-      .first();
-  },
-});
-
-/**
- * Create or update a domain verification challenge for an enterprise domain.
- *
- * If a verification record already exists for the domain, all fields are
- * updated in place (e.g. to rotate the token). Otherwise a new record is
- * created. The caller is responsible for generating the DNS record name,
- * token, and token hash.
- *
- * @param args.enterpriseId - The ID of the enterprise that owns the domain.
- * @param args.groupId - The ID of the root group that owns the enterprise.
- * @param args.domainId - The document ID of the enterprise domain to verify.
- * @param args.domain - The domain name string (e.g. `"acme.com"`).
- * @param args.recordName - The DNS TXT record name to be published (e.g. `"_convex-verify.acme.com"`).
- * @param args.token - The plaintext verification token value.
- * @param args.tokenHash - A hash of the verification token for secure storage.
- * @param args.requestedAt - Epoch timestamp (ms) when the verification was requested.
- * @param args.expiresAt - Epoch timestamp (ms) after which the challenge expires.
- * @returns The ID of the created or updated `EnterpriseDomainVerification` document.
- *
- * @example
- * ```ts
- * const verificationId = await ctx.runMutation(
- *   components.auth.enterprise.enterpriseDomainVerificationUpsert,
- *   {
- *     enterpriseId,
- *     groupId: orgGroupId,
- *     domainId,
- *     domain: "acme.com",
- *     recordName: "_convex-verify.acme.com",
- *     token: "abc123",
- *     tokenHash: "sha256:...",
- *     requestedAt: Date.now(),
- *     expiresAt: Date.now() + 7 * 24 * 60 * 60 * 1000,
- *   },
- * );
- * ```
- */
-export const enterpriseDomainVerificationUpsert = mutation({
-  args: {
-    enterpriseId: v.id("Enterprise"),
-    groupId: v.id("Group"),
-    domainId: v.id("EnterpriseDomain"),
-    domain: v.string(),
-    recordName: v.string(),
-    token: v.string(),
-    tokenHash: v.string(),
-    requestedAt: v.number(),
-    expiresAt: v.number(),
-  },
-  returns: v.id("EnterpriseDomainVerification"),
-  handler: async (ctx, args) => {
-    const existing = await ctx.db
-      .query("EnterpriseDomainVerification")
-      .withIndex("domain_id", (idx) => idx.eq("domainId", args.domainId))
-      .first();
-    if (existing) {
-      await ctx.db.patch(existing._id, args);
-      return existing._id;
-    }
-    return await ctx.db.insert("EnterpriseDomainVerification", args);
-  },
-});
-
-/**
- * Delete the pending domain verification record for an enterprise domain.
- *
- * Removes the `EnterpriseDomainVerification` document associated with the
- * given domain, effectively cancelling the verification challenge. If no
- * verification record exists, this is a no-op.
- *
- * @param args.domainId - The document ID of the enterprise domain whose verification to delete.
- * @returns `null` on success.
- *
- * @example
- * ```ts
- * await ctx.runMutation(
- *   components.auth.enterprise.enterpriseDomainVerificationDelete,
- *   { domainId },
- * );
- * ```
- */
-export const enterpriseDomainVerificationDelete = mutation({
-  args: { domainId: v.id("EnterpriseDomain") },
-  returns: v.null(),
-  handler: async (ctx, { domainId }) => {
-    const existing = await ctx.db
-      .query("EnterpriseDomainVerification")
-      .withIndex("domain_id", (idx) => idx.eq("domainId", domainId))
-      .first();
-    if (existing) {
-      await ctx.db.delete(existing._id);
-    }
-    return null;
-  },
-});
-
-/**
- * Mark an enterprise domain as verified and clean up the verification record.
- *
- * Sets the `verifiedAt` timestamp on the domain document and deletes the
- * associated `EnterpriseDomainVerification` record (if any). Throws an
- * `INVALID_PARAMETERS` error if the domain document does not exist.
- *
- * @param args.domainId - The document ID of the enterprise domain to mark as verified.
- * @param args.verifiedAt - Epoch timestamp (ms) at which the domain was verified.
- * @returns The updated enterprise domain document with the `verifiedAt` field set.
- *
- * @example
- * ```ts
- * const verifiedDomain = await ctx.runMutation(
- *   components.auth.enterprise.enterpriseDomainVerify,
- *   { domainId, verifiedAt: Date.now() },
- * );
- * console.log("Domain verified:", verifiedDomain.domain);
- * ```
- */
-export const enterpriseDomainVerify = mutation({
-  args: {
-    domainId: v.id("EnterpriseDomain"),
-    verifiedAt: v.number(),
-  },
-  returns: vEnterpriseDomainDoc,
-  handler: async (ctx, { domainId, verifiedAt }) => {
-    await ctx.db.patch(domainId, { verifiedAt });
-    const domain = await ctx.db.get("EnterpriseDomain", domainId);
-    if (!domain) {
-      throw new ConvexError({
-        code: "INVALID_PARAMETERS",
-        message: "Enterprise domain not found.",
-      });
-    }
-    const verification = await ctx.db
-      .query("EnterpriseDomainVerification")
-      .withIndex("domain_id", (idx) => idx.eq("domainId", domainId))
-      .first();
-    if (verification) {
-      await ctx.db.delete(verification._id);
-    }
-    return domain;
-  },
-});