@robelest/convex-auth 0.0.4-preview.2 → 0.0.4-preview.21

package/dist/component/public/factors/totp.js

@@ -0,0 +1,254 @@
+import { mutation, query } from "../../functions.js";
+import { vTotpFactorDoc } from "../../model.js";
+import { v } from "convex/values";
+
+//#region src/component/public/factors/totp.ts
+/**
+* Store a new TOTP (Time-based One-Time Password) enrollment for a user.
+*
+* Creates a `TotpFactor` record containing the shared secret and OTP
+* parameters. The enrollment starts in an unverified state until the
+* user confirms it by submitting a valid code generated from the secret.
+*
+* @param userId - The `_id` of the `User` enrolling in TOTP-based 2FA.
+* @param secret - The shared secret key as raw bytes, typically 20 bytes
+*   of cryptographically random data.
+* @param digits - Number of digits in the generated OTP code (usually `6`).
+* @param period - Time step in seconds for code generation (usually `30`).
+* @param verified - Whether the enrollment has been verified. Set to
+*   `false` during initial setup; set to `true` after the user submits
+*   a valid code.
+* @param name - Optional human-readable label for the TOTP factor
+*   (e.g. `"Google Authenticator"`).
+* @param createdAt - Unix timestamp (in milliseconds) when the enrollment
+*   was created.
+* @returns The `_id` of the newly created `TotpFactor` document.
+*
+* @example
+* ```ts
+* const totpId = await ctx.runMutation(
+*   components.auth.factors.totp.totpInsert,
+*   {
+*     userId: user._id,
+*     secret: crypto.getRandomValues(new Uint8Array(20)),
+*     digits: 6,
+*     period: 30,
+*     verified: false,
+*     name: "Authenticator App",
+*     createdAt: Date.now(),
+*   },
+* );
+* ```
+*/
+const totpInsert = mutation({
+	args: {
+		userId: v.id("User"),
+		secret: v.bytes(),
+		digits: v.number(),
+		period: v.number(),
+		verified: v.boolean(),
+		name: v.optional(v.string()),
+		createdAt: v.number()
+	},
+	returns: v.id("TotpFactor"),
+	handler: async (ctx, args) => {
+		return await ctx.db.insert("TotpFactor", args);
+	}
+});
+/**
+* Get a verified TOTP enrollment for a user.
+*
+* Queries the `TotpFactor` table using the `user_id_verified` compound
+* index to find the first enrollment that has been successfully verified.
+* This is the primary lookup during a TOTP authentication challenge --
+* only verified enrollments should be used to validate codes.
+*
+* @param userId - The `_id` of the `User` whose verified TOTP enrollment
+*   to retrieve.
+* @returns The first verified `TotpFactor` document for the user, or
+*   `null` if the user has no verified TOTP enrollment.
+*
+* @example
+* ```ts
+* const totp = await ctx.runQuery(
+*   components.auth.factors.totp.totpGetVerifiedByUserId,
+*   { userId: user._id },
+* );
+* if (totp === null) {
+*   // User does not have TOTP 2FA enabled
+* }
+* ```
+*/
+const totpGetVerifiedByUserId = query({
+	args: { userId: v.id("User") },
+	returns: v.union(vTotpFactorDoc, v.null()),
+	handler: async (ctx, { userId }) => {
+		return await ctx.db.query("TotpFactor").withIndex("user_id_verified", (q) => q.eq("userId", userId).eq("verified", true)).first();
+	}
+});
+/**
+* List all TOTP enrollments for a user, both verified and unverified.
+*
+* Retrieves every `TotpFactor` document associated with the given user
+* via the `user_id` index. Useful for displaying enrolled authenticator
+* apps in a security settings page, including pending (unverified)
+* enrollments that the user has not yet confirmed.
+*
+* @param userId - The `_id` of the `User` whose TOTP enrollments to
+*   retrieve.
+* @returns An array of `TotpFactor` documents. Returns an empty array if
+*   the user has no TOTP enrollments.
+*
+* @example
+* ```ts
+* const factors = await ctx.runQuery(
+*   components.auth.factors.totp.totpListByUserId,
+*   { userId: user._id },
+* );
+* const verified = factors.filter((f) => f.verified);
+* const pending = factors.filter((f) => !f.verified);
+* ```
+*/
+const totpListByUserId = query({
+	args: { userId: v.id("User") },
+	returns: v.array(vTotpFactorDoc),
+	handler: async (ctx, { userId }) => {
+		return await ctx.db.query("TotpFactor").withIndex("user_id", (q) => q.eq("userId", userId)).collect();
+	}
+});
+/**
+* Get a single TOTP enrollment by its document ID.
+*
+* Performs a direct document lookup on the `TotpFactor` table. This is
+* used when you already have the enrollment's `_id` (e.g. from a
+* previous list query) and need to fetch its full details, including
+* the secret and verification status.
+*
+* @param totpId - The `_id` of the `TotpFactor` document to retrieve.
+* @returns The `TotpFactor` document, or `null` if no enrollment exists
+*   with the given ID.
+*
+* @example
+* ```ts
+* const totp = await ctx.runQuery(
+*   components.auth.factors.totp.totpGetById,
+*   { totpId: enrollmentId },
+* );
+* if (totp !== null && !totp.verified) {
+*   // Enrollment is still pending confirmation
+* }
+* ```
+*/
+const totpGetById = query({
+	args: { totpId: v.id("TotpFactor") },
+	returns: v.union(vTotpFactorDoc, v.null()),
+	handler: async (ctx, { totpId }) => {
+		return await ctx.db.get("TotpFactor", totpId);
+	}
+});
+/**
+* Mark a TOTP enrollment as verified, completing the setup process.
+*
+* Called after the user successfully submits a valid TOTP code during
+* enrollment. This transitions the factor from a pending state to an
+* active, verified state, enabling it for future authentication
+* challenges.
+*
+* @param totpId - The `_id` of the `TotpFactor` document to mark as
+*   verified.
+* @param lastUsedAt - Unix timestamp (in milliseconds) recording when
+*   the verification code was successfully validated.
+* @returns `null` on success.
+*
+* @example
+* ```ts
+* // After validating the user's TOTP code during setup
+* await ctx.runMutation(
+*   components.auth.factors.totp.totpMarkVerified,
+*   {
+*     totpId: enrollment._id,
+*     lastUsedAt: Date.now(),
+*   },
+* );
+* ```
+*/
+const totpMarkVerified = mutation({
+	args: {
+		totpId: v.id("TotpFactor"),
+		lastUsedAt: v.number()
+	},
+	returns: v.null(),
+	handler: async (ctx, { totpId, lastUsedAt }) => {
+		await ctx.db.patch("TotpFactor", totpId, {
+			verified: true,
+			lastUsedAt
+		});
+		return null;
+	}
+});
+/**
+* Update a TOTP enrollment's last-used timestamp.
+*
+* Called after each successful TOTP code validation during sign-in.
+* Tracking the last-used time helps detect stale enrollments and can
+* be surfaced in security settings for user awareness.
+*
+* @param totpId - The `_id` of the `TotpFactor` document to update.
+* @param lastUsedAt - Unix timestamp (in milliseconds) recording when
+*   the TOTP code was most recently validated.
+* @returns `null` on success.
+*
+* @example
+* ```ts
+* await ctx.runMutation(
+*   components.auth.factors.totp.totpUpdateLastUsed,
+*   {
+*     totpId: totp._id,
+*     lastUsedAt: Date.now(),
+*   },
+* );
+* ```
+*/
+const totpUpdateLastUsed = mutation({
+	args: {
+		totpId: v.id("TotpFactor"),
+		lastUsedAt: v.number()
+	},
+	returns: v.null(),
+	handler: async (ctx, { totpId, lastUsedAt }) => {
+		await ctx.db.patch("TotpFactor", totpId, { lastUsedAt });
+		return null;
+	}
+});
+/**
+* Delete a TOTP enrollment from the `TotpFactor` table.
+*
+* Permanently removes the TOTP factor record, including its shared
+* secret. After deletion the user can no longer use this factor for
+* two-factor authentication. Typically called when a user disables
+* TOTP 2FA or wants to re-enroll with a new secret.
+*
+* @param totpId - The `_id` of the `TotpFactor` document to delete.
+* @returns `null` on success.
+*
+* @example
+* ```ts
+* // User disables TOTP 2FA
+* await ctx.runMutation(
+*   components.auth.factors.totp.totpDelete,
+*   { totpId: totp._id },
+* );
+* ```
+*/
+const totpDelete = mutation({
+	args: { totpId: v.id("TotpFactor") },
+	returns: v.null(),
+	handler: async (ctx, { totpId }) => {
+		await ctx.db.delete("TotpFactor", totpId);
+		return null;
+	}
+});
+
+//#endregion
+export { totpDelete, totpGetById, totpGetVerifiedByUserId, totpInsert, totpListByUserId, totpMarkVerified, totpUpdateLastUsed };
+//# sourceMappingURL=totp.js.map

package/dist/component/public/factors/totp.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"totp.js","names":[],"sources":["../../../../src/component/public/factors/totp.ts"],"sourcesContent":["import { v } from \"convex/values\";\nimport { mutation, query } from \"../../functions\";\nimport { vTotpFactorDoc } from \"../../model\";\n\n/**\n * Store a new TOTP (Time-based One-Time Password) enrollment for a user.\n *\n * Creates a `TotpFactor` record containing the shared secret and OTP\n * parameters. The enrollment starts in an unverified state until the\n * user confirms it by submitting a valid code generated from the secret.\n *\n * @param userId - The `_id` of the `User` enrolling in TOTP-based 2FA.\n * @param secret - The shared secret key as raw bytes, typically 20 bytes\n *   of cryptographically random data.\n * @param digits - Number of digits in the generated OTP code (usually `6`).\n * @param period - Time step in seconds for code generation (usually `30`).\n * @param verified - Whether the enrollment has been verified. Set to\n *   `false` during initial setup; set to `true` after the user submits\n *   a valid code.\n * @param name - Optional human-readable label for the TOTP factor\n *   (e.g. `\"Google Authenticator\"`).\n * @param createdAt - Unix timestamp (in milliseconds) when the enrollment\n *   was created.\n * @returns The `_id` of the newly created `TotpFactor` document.\n *\n * @example\n * ```ts\n * const totpId = await ctx.runMutation(\n *   components.auth.factors.totp.totpInsert,\n *   {\n *     userId: user._id,\n *     secret: crypto.getRandomValues(new Uint8Array(20)),\n *     digits: 6,\n *     period: 30,\n *     verified: false,\n *     name: \"Authenticator App\",\n *     createdAt: Date.now(),\n *   },\n * );\n * ```\n */\nexport const totpInsert = mutation({\n  args: {\n    userId: v.id(\"User\"),\n    secret: v.bytes(),\n    digits: v.number(),\n    period: v.number(),\n    verified: v.boolean(),\n    name: v.optional(v.string()),\n    createdAt: v.number(),\n  },\n  returns: v.id(\"TotpFactor\"),\n  handler: async (ctx, args) => {\n    return await ctx.db.insert(\"TotpFactor\", args);\n  },\n});\n\n/**\n * Get a verified TOTP enrollment for a user.\n *\n * Queries the `TotpFactor` table using the `user_id_verified` compound\n * index to find the first enrollment that has been successfully verified.\n * This is the primary lookup during a TOTP authentication challenge --\n * only verified enrollments should be used to validate codes.\n *\n * @param userId - The `_id` of the `User` whose verified TOTP enrollment\n *   to retrieve.\n * @returns The first verified `TotpFactor` document for the user, or\n *   `null` if the user has no verified TOTP enrollment.\n *\n * @example\n * ```ts\n * const totp = await ctx.runQuery(\n *   components.auth.factors.totp.totpGetVerifiedByUserId,\n *   { userId: user._id },\n * );\n * if (totp === null) {\n *   // User does not have TOTP 2FA enabled\n * }\n * ```\n */\nexport const totpGetVerifiedByUserId = query({\n  args: { userId: v.id(\"User\") },\n  returns: v.union(vTotpFactorDoc, v.null()),\n  handler: async (ctx, { userId }) => {\n    return await ctx.db\n      .query(\"TotpFactor\")\n      .withIndex(\"user_id_verified\", (q) =>\n        q.eq(\"userId\", userId).eq(\"verified\", true),\n      )\n      .first();\n  },\n});\n\n/**\n * List all TOTP enrollments for a user, both verified and unverified.\n *\n * Retrieves every `TotpFactor` document associated with the given user\n * via the `user_id` index. Useful for displaying enrolled authenticator\n * apps in a security settings page, including pending (unverified)\n * enrollments that the user has not yet confirmed.\n *\n * @param userId - The `_id` of the `User` whose TOTP enrollments to\n *   retrieve.\n * @returns An array of `TotpFactor` documents. Returns an empty array if\n *   the user has no TOTP enrollments.\n *\n * @example\n * ```ts\n * const factors = await ctx.runQuery(\n *   components.auth.factors.totp.totpListByUserId,\n *   { userId: user._id },\n * );\n * const verified = factors.filter((f) => f.verified);\n * const pending = factors.filter((f) => !f.verified);\n * ```\n */\nexport const totpListByUserId = query({\n  args: { userId: v.id(\"User\") },\n  returns: v.array(vTotpFactorDoc),\n  handler: async (ctx, { userId }) => {\n    return await ctx.db\n      .query(\"TotpFactor\")\n      .withIndex(\"user_id\", (q) => q.eq(\"userId\", userId))\n      .collect();\n  },\n});\n\n/**\n * Get a single TOTP enrollment by its document ID.\n *\n * Performs a direct document lookup on the `TotpFactor` table. This is\n * used when you already have the enrollment's `_id` (e.g. from a\n * previous list query) and need to fetch its full details, including\n * the secret and verification status.\n *\n * @param totpId - The `_id` of the `TotpFactor` document to retrieve.\n * @returns The `TotpFactor` document, or `null` if no enrollment exists\n *   with the given ID.\n *\n * @example\n * ```ts\n * const totp = await ctx.runQuery(\n *   components.auth.factors.totp.totpGetById,\n *   { totpId: enrollmentId },\n * );\n * if (totp !== null && !totp.verified) {\n *   // Enrollment is still pending confirmation\n * }\n * ```\n */\nexport const totpGetById = query({\n  args: { totpId: v.id(\"TotpFactor\") },\n  returns: v.union(vTotpFactorDoc, v.null()),\n  handler: async (ctx, { totpId }) => {\n    return await ctx.db.get(\"TotpFactor\", totpId);\n  },\n});\n\n/**\n * Mark a TOTP enrollment as verified, completing the setup process.\n *\n * Called after the user successfully submits a valid TOTP code during\n * enrollment. This transitions the factor from a pending state to an\n * active, verified state, enabling it for future authentication\n * challenges.\n *\n * @param totpId - The `_id` of the `TotpFactor` document to mark as\n *   verified.\n * @param lastUsedAt - Unix timestamp (in milliseconds) recording when\n *   the verification code was successfully validated.\n * @returns `null` on success.\n *\n * @example\n * ```ts\n * // After validating the user's TOTP code during setup\n * await ctx.runMutation(\n *   components.auth.factors.totp.totpMarkVerified,\n *   {\n *     totpId: enrollment._id,\n *     lastUsedAt: Date.now(),\n *   },\n * );\n * ```\n */\nexport const totpMarkVerified = mutation({\n  args: { totpId: v.id(\"TotpFactor\"), lastUsedAt: v.number() },\n  returns: v.null(),\n  handler: async (ctx, { totpId, lastUsedAt }) => {\n    await ctx.db.patch(\"TotpFactor\", totpId, { verified: true, lastUsedAt });\n    return null;\n  },\n});\n\n/**\n * Update a TOTP enrollment's last-used timestamp.\n *\n * Called after each successful TOTP code validation during sign-in.\n * Tracking the last-used time helps detect stale enrollments and can\n * be surfaced in security settings for user awareness.\n *\n * @param totpId - The `_id` of the `TotpFactor` document to update.\n * @param lastUsedAt - Unix timestamp (in milliseconds) recording when\n *   the TOTP code was most recently validated.\n * @returns `null` on success.\n *\n * @example\n * ```ts\n * await ctx.runMutation(\n *   components.auth.factors.totp.totpUpdateLastUsed,\n *   {\n *     totpId: totp._id,\n *     lastUsedAt: Date.now(),\n *   },\n * );\n * ```\n */\nexport const totpUpdateLastUsed = mutation({\n  args: { totpId: v.id(\"TotpFactor\"), lastUsedAt: v.number() },\n  returns: v.null(),\n  handler: async (ctx, { totpId, lastUsedAt }) => {\n    await ctx.db.patch(\"TotpFactor\", totpId, { lastUsedAt });\n    return null;\n  },\n});\n\n/**\n * Delete a TOTP enrollment from the `TotpFactor` table.\n *\n * Permanently removes the TOTP factor record, including its shared\n * secret. After deletion the user can no longer use this factor for\n * two-factor authentication. Typically called when a user disables\n * TOTP 2FA or wants to re-enroll with a new secret.\n *\n * @param totpId - The `_id` of the `TotpFactor` document to delete.\n * @returns `null` on success.\n *\n * @example\n * ```ts\n * // User disables TOTP 2FA\n * await ctx.runMutation(\n *   components.auth.factors.totp.totpDelete,\n *   { totpId: totp._id },\n * );\n * ```\n */\nexport const totpDelete = mutation({\n  args: { totpId: v.id(\"TotpFactor\") },\n  returns: v.null(),\n  handler: async (ctx, { totpId }) => {\n    await ctx.db.delete(\"TotpFactor\", totpId);\n    return null;\n  },\n});\n\n// ============================================================================\n// Rate Limits\n// ============================================================================\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAyCA,MAAa,aAAa,SAAS;CACjC,MAAM;EACJ,QAAQ,EAAE,GAAG,OAAO;EACpB,QAAQ,EAAE,OAAO;EACjB,QAAQ,EAAE,QAAQ;EAClB,QAAQ,EAAE,QAAQ;EAClB,UAAU,EAAE,SAAS;EACrB,MAAM,EAAE,SAAS,EAAE,QAAQ,CAAC;EAC5B,WAAW,EAAE,QAAQ;EACtB;CACD,SAAS,EAAE,GAAG,aAAa;CAC3B,SAAS,OAAO,KAAK,SAAS;AAC5B,SAAO,MAAM,IAAI,GAAG,OAAO,cAAc,KAAK;;CAEjD,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;AA0BF,MAAa,0BAA0B,MAAM;CAC3C,MAAM,EAAE,QAAQ,EAAE,GAAG,OAAO,EAAE;CAC9B,SAAS,EAAE,MAAM,gBAAgB,EAAE,MAAM,CAAC;CAC1C,SAAS,OAAO,KAAK,EAAE,aAAa;AAClC,SAAO,MAAM,IAAI,GACd,MAAM,aAAa,CACnB,UAAU,qBAAqB,MAC9B,EAAE,GAAG,UAAU,OAAO,CAAC,GAAG,YAAY,KAAK,CAC5C,CACA,OAAO;;CAEb,CAAC;;;;;;;;;;;;;;;;;;;;;;;;AAyBF,MAAa,mBAAmB,MAAM;CACpC,MAAM,EAAE,QAAQ,EAAE,GAAG,OAAO,EAAE;CAC9B,SAAS,EAAE,MAAM,eAAe;CAChC,SAAS,OAAO,KAAK,EAAE,aAAa;AAClC,SAAO,MAAM,IAAI,GACd,MAAM,aAAa,CACnB,UAAU,YAAY,MAAM,EAAE,GAAG,UAAU,OAAO,CAAC,CACnD,SAAS;;CAEf,CAAC;;;;;;;;;;;;;;;;;;;;;;;;AAyBF,MAAa,cAAc,MAAM;CAC/B,MAAM,EAAE,QAAQ,EAAE,GAAG,aAAa,EAAE;CACpC,SAAS,EAAE,MAAM,gBAAgB,EAAE,MAAM,CAAC;CAC1C,SAAS,OAAO,KAAK,EAAE,aAAa;AAClC,SAAO,MAAM,IAAI,GAAG,IAAI,cAAc,OAAO;;CAEhD,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;AA4BF,MAAa,mBAAmB,SAAS;CACvC,MAAM;EAAE,QAAQ,EAAE,GAAG,aAAa;EAAE,YAAY,EAAE,QAAQ;EAAE;CAC5D,SAAS,EAAE,MAAM;CACjB,SAAS,OAAO,KAAK,EAAE,QAAQ,iBAAiB;AAC9C,QAAM,IAAI,GAAG,MAAM,cAAc,QAAQ;GAAE,UAAU;GAAM;GAAY,CAAC;AACxE,SAAO;;CAEV,CAAC;;;;;;;;;;;;;;;;;;;;;;;;AAyBF,MAAa,qBAAqB,SAAS;CACzC,MAAM;EAAE,QAAQ,EAAE,GAAG,aAAa;EAAE,YAAY,EAAE,QAAQ;EAAE;CAC5D,SAAS,EAAE,MAAM;CACjB,SAAS,OAAO,KAAK,EAAE,QAAQ,iBAAiB;AAC9C,QAAM,IAAI,GAAG,MAAM,cAAc,QAAQ,EAAE,YAAY,CAAC;AACxD,SAAO;;CAEV,CAAC;;;;;;;;;;;;;;;;;;;;;AAsBF,MAAa,aAAa,SAAS;CACjC,MAAM,EAAE,QAAQ,EAAE,GAAG,aAAa,EAAE;CACpC,SAAS,EAAE,MAAM;CACjB,SAAS,OAAO,KAAK,EAAE,aAAa;AAClC,QAAM,IAAI,GAAG,OAAO,cAAc,OAAO;AACzC,SAAO;;CAEV,CAAC"}

package/dist/component/public/groups/core.d.ts

@@ -0,0 +1,137 @@
+declare namespace core_d_exports {
+  export { groupCreate, groupDelete, groupGet, groupList, groupUpdate };
+}
+/**
+ * Create a new group. Groups are hierarchical — set `parentGroupId` to nest
+ * under an existing group, or omit it to create a root-level group.
+ *
+ * Root groups self-reference their own ID as `rootGroupId`. Child groups
+ * inherit `rootGroupId` from their parent chain. Tags are normalized
+ * (trimmed and lowercased) and deduplicated before storage, and companion
+ * `GroupTag` rows are created for indexed lookups.
+ *
+ * @param args.name - The display name for the group.
+ * @param args.slug - An optional URL-friendly identifier for the group (e.g. `"engineering"`).
+ * @param args.type - An optional application-defined group type (e.g. `"organization"`, `"team"`).
+ * @param args.parentGroupId - The ID of an existing group to nest under. Omit to create a root-level group.
+ * @param args.tags - An optional array of `{ key, value }` tag pairs to attach to the group for filtering.
+ * @param args.extend - An optional arbitrary payload for application-specific metadata.
+ * @returns The `Id<"Group">` of the newly created group document.
+ *
+ * @example
+ * ```ts
+ * const groupId = await ctx.runMutation(components.auth.groups.groupCreate, {
+ *   name: "Acme Corp",
+ *   slug: "acme-corp",
+ *   type: "organization",
+ *   tags: [{ key: "plan", value: "enterprise" }],
+ * });
+ * ```
+ */
+declare const groupCreate: any;
+/**
+ * Retrieve a group by its document ID.
+ *
+ * Performs a direct lookup in the `Group` table and returns the full group
+ * document, or `null` if no group exists with the given ID.
+ *
+ * @param args.groupId - The `Id<"Group">` of the group to retrieve.
+ * @returns The group document (including `name`, `slug`, `type`, `tags`, hierarchy fields, etc.) or `null` if not found.
+ *
+ * @example
+ * ```ts
+ * const group = await ctx.runQuery(components.auth.groups.groupGet, {
+ *   groupId: existingGroupId,
+ * });
+ * if (group !== null) {
+ *   console.log(group.name, group.slug);
+ * }
+ * ```
+ */
+declare const groupGet: any;
+/**
+ * List groups with optional filtering, sorting, and pagination.
+ *
+ * Returns `{ items, nextCursor }`. Empty `where` returns **all** groups.
+ * The query engine selects the best database index based on the combination
+ * of filter fields provided. Tag filters (`tagsAll`, `tagsAny`) are resolved
+ * via the `GroupTag` companion table and intersected/unioned with index results.
+ *
+ * @param args.where - Optional filter criteria for narrowing results.
+ * @param args.where.slug - Match groups with this exact slug.
+ * @param args.where.type - Match groups with this exact type.
+ * @param args.where.parentGroupId - Match groups that are direct children of the specified parent group.
+ * @param args.where.name - Match groups with this exact name.
+ * @param args.where.isRoot - When `true`, return only root-level groups; when `false`, only child groups.
+ * @param args.where.tagsAll - An array of `{ key, value }` pairs; only groups that have **all** of these tags are returned.
+ * @param args.where.tagsAny - An array of `{ key, value }` pairs; groups that have **at least one** of these tags are returned.
+ * @param args.limit - Maximum number of items per page (clamped to 1..100, defaults to 50).
+ * @param args.cursor - An opaque cursor string from a previous response's `nextCursor` to fetch the next page, or `null` to start from the beginning.
+ * @param args.orderBy - The field to sort by: `"_creationTime"`, `"name"`, `"slug"`, or `"type"`.
+ * @param args.order - Sort direction: `"asc"` or `"desc"` (defaults to `"desc"`).
+ * @returns An object `{ items, nextCursor }` where `items` is an array of group documents and `nextCursor` is `null` when there are no more pages.
+ *
+ * @example
+ * ```ts
+ * const { items, nextCursor } = await ctx.runQuery(
+ *   components.auth.groups.groupList,
+ *   {
+ *     where: { type: "team", isRoot: false },
+ *     limit: 20,
+ *     order: "asc",
+ *   },
+ * );
+ * ```
+ */
+declare const groupList: any;
+/**
+ * Update a group's mutable fields such as `name`, `slug`, `tags`, `extend`,
+ * and `parentGroupId`.
+ *
+ * When `parentGroupId` is changed the mutation automatically recomputes
+ * `isRoot` and `rootGroupId` for the target group **and** cascades the new
+ * `rootGroupId` to all descendant groups. When `tags` are provided they are
+ * normalized, deduplicated, and the companion `GroupTag` rows are fully
+ * replaced (delete-then-insert).
+ *
+ * @param args.groupId - The `Id<"Group">` of the group to update.
+ * @param args.data - A partial object of fields to patch. Supported keys include `name`, `slug`, `type`, `parentGroupId`, `tags`, and `extend`.
+ * @returns `null` on success.
+ *
+ * @example
+ * ```ts
+ * await ctx.runMutation(components.auth.groups.groupUpdate, {
+ *   groupId: existingGroupId,
+ *   data: {
+ *     name: "Acme Corp (renamed)",
+ *     tags: [{ key: "plan", value: "pro" }],
+ *   },
+ * });
+ * ```
+ */
+declare const groupUpdate: any;
+/**
+ * Delete a group and all of its descendants. This cascades to:
+ * - All child groups (recursively)
+ * - All members of this group and its descendants
+ * - All invites for this group and its descendants
+ * - All companion `GroupTag` rows for this group and its descendants
+ *
+ * The deletion walks the group tree depth-first, removing leaves before
+ * parents, so referential integrity is maintained throughout.
+ *
+ * @param args.groupId - The `Id<"Group">` of the group to delete. All children are deleted recursively.
+ * @returns `null` on success.
+ *
+ * @example
+ * ```ts
+ * // Delete an organization and everything nested under it
+ * await ctx.runMutation(components.auth.groups.groupDelete, {
+ *   groupId: organizationGroupId,
+ * });
+ * ```
+ */
+declare const groupDelete: any;
+//#endregion
+export { core_d_exports, groupCreate, groupDelete, groupGet, groupList, groupUpdate };
+//# sourceMappingURL=core.d.ts.map

package/dist/component/public/groups/core.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"core.d.ts","names":[],"sources":["../../../../src/component/public/groups/core.ts"],"mappings":";;;;;;;;;;;;;AAuDA;;;;;AA+DA;;;;;AA0CA;;;;;AAsLA;;cA/Ra,WAAA;;;AAyXb;;;;;;;;;;;;;;;;;cA1Ta,QAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;cA0CA,SAAA;;;;;;;;;;;;;;;;;;;;;;;;;;cAsLA,WAAA;;;;;;;;;;;;;;;;;;;;;;cA0FA,WAAA"}