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

package/dist/component/public/groups/core.js

@@ -0,0 +1,321 @@
+import { mutation, query } from "../../functions.js";
+import { vGroupDoc, vPaginated, vTag } from "../../model.js";
+import { v } from "convex/values";
+
+//#region src/component/public/groups/core.ts
+function normalizeTag(tag) {
+	return {
+		key: tag.key.trim().toLowerCase(),
+		value: tag.value.trim().toLowerCase()
+	};
+}
+function normalizeTags(tags) {
+	const seen = /* @__PURE__ */ new Set();
+	const result = [];
+	for (const raw of tags) {
+		const t = normalizeTag(raw);
+		const composite = `${t.key}\0${t.value}`;
+		if (!seen.has(composite)) {
+			seen.add(composite);
+			result.push(t);
+		}
+	}
+	return result;
+}
+/**
+* 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" }],
+* });
+* ```
+*/
+const groupCreate = mutation({
+	args: {
+		name: v.string(),
+		slug: v.optional(v.string()),
+		type: v.optional(v.string()),
+		parentGroupId: v.optional(v.id("Group")),
+		tags: v.optional(v.array(vTag)),
+		extend: v.optional(v.any())
+	},
+	returns: v.id("Group"),
+	handler: async (ctx, args) => {
+		const { tags: rawTags, ...rest } = args;
+		const normalizedTags = rawTags ? normalizeTags(rawTags) : void 0;
+		const isRoot = !args.parentGroupId;
+		let rootGroupId;
+		if (!isRoot && args.parentGroupId) rootGroupId = (await ctx.db.get(args.parentGroupId))?.rootGroupId ?? args.parentGroupId;
+		const groupId = await ctx.db.insert("Group", {
+			...rest,
+			tags: normalizedTags,
+			isRoot,
+			rootGroupId: isRoot ? void 0 : rootGroupId
+		});
+		if (isRoot) await ctx.db.patch(groupId, { rootGroupId: groupId });
+		if (normalizedTags) for (const tag of normalizedTags) await ctx.db.insert("GroupTag", {
+			group_id: groupId,
+			key: tag.key,
+			value: tag.value
+		});
+		return groupId;
+	}
+});
+/**
+* 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);
+* }
+* ```
+*/
+const groupGet = query({
+	args: { groupId: v.id("Group") },
+	returns: v.union(vGroupDoc, v.null()),
+	handler: async (ctx, { groupId }) => {
+		return await ctx.db.get("Group", groupId);
+	}
+});
+/**
+* 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",
+*   },
+* );
+* ```
+*/
+const groupList = query({
+	args: {
+		where: v.optional(v.object({
+			slug: v.optional(v.string()),
+			type: v.optional(v.string()),
+			parentGroupId: v.optional(v.id("Group")),
+			name: v.optional(v.string()),
+			isRoot: v.optional(v.boolean()),
+			tagsAll: v.optional(v.array(vTag)),
+			tagsAny: v.optional(v.array(vTag))
+		})),
+		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("type"))),
+		order: v.optional(v.union(v.literal("asc"), v.literal("desc")))
+	},
+	returns: vPaginated(vGroupDoc),
+	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 tagFilteredIds = null;
+		if (where.tagsAll && where.tagsAll.length > 0) {
+			let allSet = null;
+			for (const rawTag of where.tagsAll) {
+				const t = normalizeTag(rawTag);
+				const rows = await ctx.db.query("GroupTag").withIndex("by_key_value", (idx) => idx.eq("key", t.key).eq("value", t.value)).collect();
+				const ids = new Set(rows.map((r) => r.group_id));
+				if (allSet === null) allSet = ids;
+				else for (const id of allSet) if (!ids.has(id)) allSet.delete(id);
+				if (allSet.size === 0) break;
+			}
+			tagFilteredIds = allSet ?? /* @__PURE__ */ new Set();
+		}
+		if (where.tagsAny && where.tagsAny.length > 0) {
+			const anySet = /* @__PURE__ */ new Set();
+			for (const rawTag of where.tagsAny) {
+				const t = normalizeTag(rawTag);
+				const rows = await ctx.db.query("GroupTag").withIndex("by_key_value", (idx) => idx.eq("key", t.key).eq("value", t.value)).collect();
+				for (const r of rows) anySet.add(r.group_id);
+			}
+			if (tagFilteredIds !== null) {
+				for (const id of tagFilteredIds) if (!anySet.has(id)) tagFilteredIds.delete(id);
+			} else tagFilteredIds = anySet;
+		}
+		let q;
+		if (where.type !== void 0 && where.parentGroupId !== void 0) q = ctx.db.query("Group").withIndex("type_parent_group_id", (idx) => idx.eq("type", where.type).eq("parentGroupId", where.parentGroupId));
+		else if (where.slug !== void 0) q = ctx.db.query("Group").withIndex("slug", (idx) => idx.eq("slug", where.slug));
+		else if (where.type !== void 0) q = ctx.db.query("Group").withIndex("type", (idx) => idx.eq("type", where.type));
+		else if (where.parentGroupId !== void 0) q = ctx.db.query("Group").withIndex("parent_group_id", (idx) => idx.eq("parentGroupId", where.parentGroupId));
+		else if (where.isRoot !== void 0) q = ctx.db.query("Group").withIndex("is_root", (idx) => idx.eq("isRoot", where.isRoot));
+		else q = ctx.db.query("Group");
+		if (where.name !== void 0) q = q.filter((f) => f.eq(f.field("name"), where.name));
+		if (where.isRoot !== void 0 && where.parentGroupId === void 0 && (where.type !== void 0 || where.slug !== void 0)) q = q.filter((f) => f.eq(f.field("isRoot"), where.isRoot));
+		if (where.slug !== void 0 && where.type !== void 0) q = q.filter((f) => f.eq(f.field("slug"), where.slug));
+		q = q.order(order);
+		let all = await q.collect();
+		if (tagFilteredIds !== null) all = all.filter((doc) => tagFilteredIds.has(doc._id));
+		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;
+		return {
+			items,
+			nextCursor: hasMore ? items[items.length - 1]._id : null
+		};
+	}
+});
+/**
+* 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" }],
+*   },
+* });
+* ```
+*/
+const groupUpdate = mutation({
+	args: {
+		groupId: v.id("Group"),
+		data: v.any()
+	},
+	returns: v.null(),
+	handler: async (ctx, { groupId, data }) => {
+		if (data.parentGroupId !== void 0) {
+			const oldRootGroupId = (await ctx.db.get("Group", groupId))?.rootGroupId;
+			const newParentGroupId = data.parentGroupId;
+			const newIsRoot = !newParentGroupId;
+			let newRootGroupId;
+			if (newIsRoot) newRootGroupId = groupId;
+			else newRootGroupId = (await ctx.db.get("Group", newParentGroupId))?.rootGroupId ?? newParentGroupId;
+			data.isRoot = newIsRoot;
+			data.rootGroupId = newRootGroupId;
+			if (oldRootGroupId && oldRootGroupId !== newRootGroupId) {
+				const descendants = await ctx.db.query("Group").withIndex("root_group_id", (q) => q.eq("rootGroupId", oldRootGroupId)).collect();
+				for (const desc of descendants) if (desc._id !== groupId) await ctx.db.patch("Group", desc._id, { rootGroupId: newRootGroupId });
+			}
+		}
+		if (data.tags !== void 0) {
+			const normalizedTags = Array.isArray(data.tags) ? normalizeTags(data.tags) : [];
+			const existingTags = await ctx.db.query("GroupTag").withIndex("by_group", (idx) => idx.eq("group_id", groupId)).collect();
+			for (const existing of existingTags) await ctx.db.delete("GroupTag", existing._id);
+			for (const tag of normalizedTags) await ctx.db.insert("GroupTag", {
+				group_id: groupId,
+				key: tag.key,
+				value: tag.value
+			});
+			await ctx.db.patch("Group", groupId, {
+				...data,
+				tags: normalizedTags.length > 0 ? normalizedTags : void 0
+			});
+		} else await ctx.db.patch("Group", groupId, data);
+		return null;
+	}
+});
+/**
+* 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,
+* });
+* ```
+*/
+const groupDelete = mutation({
+	args: { groupId: v.id("Group") },
+	returns: v.null(),
+	handler: async (ctx, { groupId }) => {
+		const deleteGroup = async (id) => {
+			const children = await ctx.db.query("Group").withIndex("parent_group_id", (q) => q.eq("parentGroupId", id)).collect();
+			for (const child of children) await deleteGroup(child._id);
+			const members = await ctx.db.query("GroupMember").withIndex("group_id", (q) => q.eq("groupId", id)).collect();
+			for (const member of members) await ctx.db.delete("GroupMember", member._id);
+			const invites = await ctx.db.query("GroupInvite").withIndex("group_id", (q) => q.eq("groupId", id)).collect();
+			for (const invite of invites) await ctx.db.delete("GroupInvite", invite._id);
+			const tags = await ctx.db.query("GroupTag").withIndex("by_group", (q) => q.eq("group_id", id)).collect();
+			for (const tag of tags) await ctx.db.delete("GroupTag", tag._id);
+			await ctx.db.delete("Group", id);
+		};
+		await deleteGroup(groupId);
+		return null;
+	}
+});
+
+//#endregion
+export { groupCreate, groupDelete, groupGet, groupList, groupUpdate };
+//# sourceMappingURL=core.js.map

package/dist/component/public/groups/core.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"core.js","names":[],"sources":["../../../../src/component/public/groups/core.ts"],"sourcesContent":["import { v } from \"convex/values\";\nimport type { Id } from \"../../_generated/dataModel\";\nimport { mutation, query } from \"../../functions\";\nimport { vGroupDoc, vPaginated, vTag } from \"../../model\";\n\n\ntype TagPair = { key: string; value: string };\n\nfunction normalizeTag(tag: TagPair): TagPair {\n  return {\n    key: tag.key.trim().toLowerCase(),\n    value: tag.value.trim().toLowerCase(),\n  };\n}\n\nfunction normalizeTags(tags: TagPair[]): TagPair[] {\n  const seen = new Set<string>();\n  const result: TagPair[] = [];\n  for (const raw of tags) {\n    const t = normalizeTag(raw);\n    const composite = `${t.key}\\0${t.value}`;\n    if (!seen.has(composite)) {\n      seen.add(composite);\n      result.push(t);\n    }\n  }\n  return result;\n}\n/**\n * Create a new group. Groups are hierarchical — set `parentGroupId` to nest\n * under an existing group, or omit it to create a root-level group.\n *\n * Root groups self-reference their own ID as `rootGroupId`. Child groups\n * inherit `rootGroupId` from their parent chain. Tags are normalized\n * (trimmed and lowercased) and deduplicated before storage, and companion\n * `GroupTag` rows are created for indexed lookups.\n *\n * @param args.name - The display name for the group.\n * @param args.slug - An optional URL-friendly identifier for the group (e.g. `\"engineering\"`).\n * @param args.type - An optional application-defined group type (e.g. `\"organization\"`, `\"team\"`).\n * @param args.parentGroupId - The ID of an existing group to nest under. Omit to create a root-level group.\n * @param args.tags - An optional array of `{ key, value }` tag pairs to attach to the group for filtering.\n * @param args.extend - An optional arbitrary payload for application-specific metadata.\n * @returns The `Id<\"Group\">` of the newly created group document.\n *\n * @example\n * ```ts\n * const groupId = await ctx.runMutation(components.auth.groups.groupCreate, {\n *   name: \"Acme Corp\",\n *   slug: \"acme-corp\",\n *   type: \"organization\",\n *   tags: [{ key: \"plan\", value: \"enterprise\" }],\n * });\n * ```\n */\nexport const groupCreate = mutation({\n  args: {\n    name: v.string(),\n    slug: v.optional(v.string()),\n    type: v.optional(v.string()),\n    parentGroupId: v.optional(v.id(\"Group\")),\n    tags: v.optional(v.array(vTag)),\n    extend: v.optional(v.any()),\n  },\n  returns: v.id(\"Group\"),\n  handler: async (ctx, args) => {\n    const { tags: rawTags, ...rest } = args;\n    const normalizedTags = rawTags ? normalizeTags(rawTags) : undefined;\n    const isRoot = !args.parentGroupId;\n    // Compute rootGroupId: root groups self-reference, children inherit from parent\n    let rootGroupId: Id<\"Group\"> | undefined;\n    if (!isRoot && args.parentGroupId) {\n      const parent = await ctx.db.get(args.parentGroupId);\n      rootGroupId = parent?.rootGroupId ?? args.parentGroupId;\n    }\n    const groupId = await ctx.db.insert(\"Group\", {\n      ...rest,\n      tags: normalizedTags,\n      isRoot,\n      rootGroupId: isRoot ? undefined : rootGroupId,\n    });\n    // Self-reference for root groups (need the ID after insert)\n    if (isRoot) {\n      await ctx.db.patch(groupId, { rootGroupId: groupId });\n    }\n    // Sync companion group_tag rows\n    if (normalizedTags) {\n      for (const tag of normalizedTags) {\n        await ctx.db.insert(\"GroupTag\", {\n          group_id: groupId,\n          key: tag.key,\n          value: tag.value,\n        });\n      }\n    }\n    return groupId;\n  },\n});\n\n/**\n * Retrieve a group by its document ID.\n *\n * Performs a direct lookup in the `Group` table and returns the full group\n * document, or `null` if no group exists with the given ID.\n *\n * @param args.groupId - The `Id<\"Group\">` of the group to retrieve.\n * @returns The group document (including `name`, `slug`, `type`, `tags`, hierarchy fields, etc.) or `null` if not found.\n *\n * @example\n * ```ts\n * const group = await ctx.runQuery(components.auth.groups.groupGet, {\n *   groupId: existingGroupId,\n * });\n * if (group !== null) {\n *   console.log(group.name, group.slug);\n * }\n * ```\n */\nexport const groupGet = query({\n  args: { groupId: v.id(\"Group\") },\n  returns: v.union(vGroupDoc, v.null()),\n  handler: async (ctx, { groupId }) => {\n    return await ctx.db.get(\"Group\", groupId);\n  },\n});\n\n/**\n * List groups with optional filtering, sorting, and pagination.\n *\n * Returns `{ items, nextCursor }`. Empty `where` returns **all** groups.\n * The query engine selects the best database index based on the combination\n * of filter fields provided. Tag filters (`tagsAll`, `tagsAny`) are resolved\n * via the `GroupTag` companion table and intersected/unioned with index results.\n *\n * @param args.where - Optional filter criteria for narrowing results.\n * @param args.where.slug - Match groups with this exact slug.\n * @param args.where.type - Match groups with this exact type.\n * @param args.where.parentGroupId - Match groups that are direct children of the specified parent group.\n * @param args.where.name - Match groups with this exact name.\n * @param args.where.isRoot - When `true`, return only root-level groups; when `false`, only child groups.\n * @param args.where.tagsAll - An array of `{ key, value }` pairs; only groups that have **all** of these tags are returned.\n * @param args.where.tagsAny - An array of `{ key, value }` pairs; groups that have **at least one** of these tags are returned.\n * @param args.limit - Maximum number of items per page (clamped to 1..100, defaults to 50).\n * @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.\n * @param args.orderBy - The field to sort by: `\"_creationTime\"`, `\"name\"`, `\"slug\"`, or `\"type\"`.\n * @param args.order - Sort direction: `\"asc\"` or `\"desc\"` (defaults to `\"desc\"`).\n * @returns An object `{ items, nextCursor }` where `items` is an array of group documents and `nextCursor` is `null` when there are no more pages.\n *\n * @example\n * ```ts\n * const { items, nextCursor } = await ctx.runQuery(\n *   components.auth.groups.groupList,\n *   {\n *     where: { type: \"team\", isRoot: false },\n *     limit: 20,\n *     order: \"asc\",\n *   },\n * );\n * ```\n */\nexport const groupList = query({\n  args: {\n    where: v.optional(\n      v.object({\n        slug: v.optional(v.string()),\n        type: v.optional(v.string()),\n        parentGroupId: v.optional(v.id(\"Group\")),\n        name: v.optional(v.string()),\n        isRoot: v.optional(v.boolean()),\n        tagsAll: v.optional(v.array(vTag)),\n        tagsAny: v.optional(v.array(vTag)),\n      }),\n    ),\n    limit: v.optional(v.number()),\n    cursor: v.optional(v.union(v.string(), v.null())),\n    orderBy: v.optional(\n      v.union(\n        v.literal(\"_creationTime\"),\n        v.literal(\"name\"),\n        v.literal(\"slug\"),\n        v.literal(\"type\"),\n      ),\n    ),\n    order: v.optional(v.union(v.literal(\"asc\"), v.literal(\"desc\"))),\n  },\n  returns: vPaginated(vGroupDoc),\n  handler: async (ctx, args) => {\n    const where = args.where ?? {};\n    const limit = Math.min(Math.max(args.limit ?? 50, 1), 100);\n    const order = args.order ?? \"desc\";\n\n    // ---- Resolve tag filters into a Set<Id<\"Group\">> ----\n    let tagFilteredIds: Set<string> | null = null;\n\n    if (where.tagsAll && where.tagsAll.length > 0) {\n      // Intersect: group must have ALL specified tags\n      let allSet: Set<string> | null = null;\n      for (const rawTag of where.tagsAll) {\n        const t = normalizeTag(rawTag);\n        const rows = await ctx.db\n          .query(\"GroupTag\")\n          .withIndex(\"by_key_value\", (idx) =>\n            idx.eq(\"key\", t.key).eq(\"value\", t.value),\n          )\n          .collect();\n        const ids = new Set(rows.map((r) => r.group_id as string));\n        if (allSet === null) {\n          allSet = ids;\n        } else {\n          // Intersect\n          for (const id of allSet) {\n            if (!ids.has(id)) allSet.delete(id);\n          }\n        }\n        // Short-circuit: empty intersection\n        if (allSet.size === 0) break;\n      }\n      tagFilteredIds = allSet ?? new Set();\n    }\n\n    if (where.tagsAny && where.tagsAny.length > 0) {\n      // Union: group must have at least one of the specified tags\n      const anySet = new Set<string>();\n      for (const rawTag of where.tagsAny) {\n        const t = normalizeTag(rawTag);\n        const rows = await ctx.db\n          .query(\"GroupTag\")\n          .withIndex(\"by_key_value\", (idx) =>\n            idx.eq(\"key\", t.key).eq(\"value\", t.value),\n          )\n          .collect();\n        for (const r of rows) {\n          anySet.add(r.group_id as string);\n        }\n      }\n      if (tagFilteredIds !== null) {\n        // AND with tagsAll result\n        for (const id of tagFilteredIds) {\n          if (!anySet.has(id)) tagFilteredIds.delete(id);\n        }\n      } else {\n        tagFilteredIds = anySet;\n      }\n    }\n\n    // ---- Pick best index based on non-tag where fields ----\n    let q;\n    if (where.type !== undefined && where.parentGroupId !== undefined) {\n      q = ctx.db\n        .query(\"Group\")\n        .withIndex(\"type_parent_group_id\", (idx) =>\n          idx.eq(\"type\", where.type!).eq(\"parentGroupId\", where.parentGroupId!),\n        );\n    } else if (where.slug !== undefined) {\n      q = ctx.db\n        .query(\"Group\")\n        .withIndex(\"slug\", (idx) => idx.eq(\"slug\", where.slug!));\n    } else if (where.type !== undefined) {\n      q = ctx.db\n        .query(\"Group\")\n        .withIndex(\"type\", (idx) => idx.eq(\"type\", where.type!));\n    } else if (where.parentGroupId !== undefined) {\n      q = ctx.db\n        .query(\"Group\")\n        .withIndex(\"parent_group_id\", (idx) =>\n          idx.eq(\"parentGroupId\", where.parentGroupId!),\n        );\n    } else if (where.isRoot !== undefined) {\n      q = ctx.db\n        .query(\"Group\")\n        .withIndex(\"is_root\", (idx) => idx.eq(\"isRoot\", where.isRoot!));\n    } else {\n      q = ctx.db.query(\"Group\");\n    }\n\n    // Apply remaining non-tag filters not covered by index\n    if (where.name !== undefined) {\n      q = q.filter((f) => f.eq(f.field(\"name\"), where.name!));\n    }\n    // isRoot filter when not already used as primary index\n    if (\n      where.isRoot !== undefined &&\n      where.parentGroupId === undefined &&\n      (where.type !== undefined || where.slug !== undefined)\n    ) {\n      q = q.filter((f) => f.eq(f.field(\"isRoot\"), where.isRoot!));\n    }\n    // slug filter when not used as index\n    if (where.slug !== undefined && where.type !== undefined) {\n      q = q.filter((f) => f.eq(f.field(\"slug\"), where.slug!));\n    }\n\n    q = q.order(order);\n\n    let all = await q.collect();\n\n    // Apply tag filter (intersect with resolved groupIds)\n    if (tagFilteredIds !== null) {\n      all = all.filter((doc) => tagFilteredIds!.has(doc._id as string));\n    }\n\n    // Cursor-based pagination\n    let startIdx = 0;\n    if (args.cursor) {\n      const cursorIdx = all.findIndex((doc) => doc._id === args.cursor);\n      if (cursorIdx !== -1) {\n        startIdx = cursorIdx + 1;\n      }\n    }\n    const page = all.slice(startIdx, startIdx + limit + 1);\n    const hasMore = page.length > limit;\n    const items = hasMore ? page.slice(0, limit) : page;\n    const nextCursor = hasMore ? items[items.length - 1]._id : null;\n    return { items, nextCursor };\n  },\n});\n\n/**\n * Update a group's mutable fields such as `name`, `slug`, `tags`, `extend`,\n * and `parentGroupId`.\n *\n * When `parentGroupId` is changed the mutation automatically recomputes\n * `isRoot` and `rootGroupId` for the target group **and** cascades the new\n * `rootGroupId` to all descendant groups. When `tags` are provided they are\n * normalized, deduplicated, and the companion `GroupTag` rows are fully\n * replaced (delete-then-insert).\n *\n * @param args.groupId - The `Id<\"Group\">` of the group to update.\n * @param args.data - A partial object of fields to patch. Supported keys include `name`, `slug`, `type`, `parentGroupId`, `tags`, and `extend`.\n * @returns `null` on success.\n *\n * @example\n * ```ts\n * await ctx.runMutation(components.auth.groups.groupUpdate, {\n *   groupId: existingGroupId,\n *   data: {\n *     name: \"Acme Corp (renamed)\",\n *     tags: [{ key: \"plan\", value: \"pro\" }],\n *   },\n * });\n * ```\n */\nexport const groupUpdate = mutation({\n  args: { groupId: v.id(\"Group\"), data: v.any() },\n  returns: v.null(),\n  handler: async (ctx, { groupId, data }) => {\n    // If parentGroupId is changing, recompute rootGroupId + isRoot for this group and descendants\n    if (data.parentGroupId !== undefined) {\n      const oldGroup = await ctx.db.get(\"Group\", groupId);\n      const oldRootGroupId = oldGroup?.rootGroupId;\n      const newParentGroupId = data.parentGroupId as Id<\"Group\"> | undefined;\n      const newIsRoot = !newParentGroupId;\n      let newRootGroupId: Id<\"Group\">;\n      if (newIsRoot) {\n        newRootGroupId = groupId;\n      } else {\n        const parent = await ctx.db.get(\"Group\", newParentGroupId!);\n        newRootGroupId = parent?.rootGroupId ?? newParentGroupId!;\n      }\n      data.isRoot = newIsRoot;\n      data.rootGroupId = newRootGroupId;\n      // Cascade to descendants if rootGroupId changed\n      if (oldRootGroupId && oldRootGroupId !== newRootGroupId) {\n        const descendants = await ctx.db\n          .query(\"Group\")\n          .withIndex(\"root_group_id\", (q) =>\n            q.eq(\"rootGroupId\", oldRootGroupId),\n          )\n          .collect();\n        for (const desc of descendants) {\n          if (desc._id !== groupId) {\n            await ctx.db.patch(\"Group\", desc._id, {\n              rootGroupId: newRootGroupId,\n            });\n          }\n        }\n      }\n    }\n    // If tags are being updated, normalize and replace the full tag set\n    if (data.tags !== undefined) {\n      const normalizedTags: TagPair[] = Array.isArray(data.tags)\n        ? normalizeTags(data.tags as TagPair[])\n        : [];\n      // Delete existing group_tag rows for this group\n      const existingTags = await ctx.db\n        .query(\"GroupTag\")\n        .withIndex(\"by_group\", (idx) => idx.eq(\"group_id\", groupId))\n        .collect();\n      for (const existing of existingTags) {\n        await ctx.db.delete(\"GroupTag\", existing._id);\n      }\n      // Insert new normalized group_tag rows\n      for (const tag of normalizedTags) {\n        await ctx.db.insert(\"GroupTag\", {\n          group_id: groupId,\n          key: tag.key,\n          value: tag.value,\n        });\n      }\n      // Patch group with normalized tags (empty array = clear all)\n      await ctx.db.patch(\"Group\", groupId, {\n        ...data,\n        tags: normalizedTags.length > 0 ? normalizedTags : undefined,\n      });\n    } else {\n      await ctx.db.patch(\"Group\", groupId, data);\n    }\n    return null;\n  },\n});\n\n/**\n * Delete a group and all of its descendants. This cascades to:\n * - All child groups (recursively)\n * - All members of this group and its descendants\n * - All invites for this group and its descendants\n * - All companion `GroupTag` rows for this group and its descendants\n *\n * The deletion walks the group tree depth-first, removing leaves before\n * parents, so referential integrity is maintained throughout.\n *\n * @param args.groupId - The `Id<\"Group\">` of the group to delete. All children are deleted recursively.\n * @returns `null` on success.\n *\n * @example\n * ```ts\n * // Delete an organization and everything nested under it\n * await ctx.runMutation(components.auth.groups.groupDelete, {\n *   groupId: organizationGroupId,\n * });\n * ```\n */\nexport const groupDelete = mutation({\n  args: { groupId: v.id(\"Group\") },\n  returns: v.null(),\n  handler: async (ctx, { groupId }) => {\n    const deleteGroup = async (id: typeof groupId) => {\n      const children = await ctx.db\n        .query(\"Group\")\n        .withIndex(\"parent_group_id\", (q) => q.eq(\"parentGroupId\", id))\n        .collect();\n      for (const child of children) {\n        await deleteGroup(child._id);\n      }\n\n      const members = await ctx.db\n        .query(\"GroupMember\")\n        .withIndex(\"group_id\", (q) => q.eq(\"groupId\", id))\n        .collect();\n      for (const member of members) {\n        await ctx.db.delete(\"GroupMember\", member._id);\n      }\n\n      const invites = await ctx.db\n        .query(\"GroupInvite\")\n        .withIndex(\"group_id\", (q) => q.eq(\"groupId\", id))\n        .collect();\n      for (const invite of invites) {\n        await ctx.db.delete(\"GroupInvite\", invite._id);\n      }\n\n      // Delete companion group_tag rows\n      const tags = await ctx.db\n        .query(\"GroupTag\")\n        .withIndex(\"by_group\", (q) => q.eq(\"group_id\", id))\n        .collect();\n      for (const tag of tags) {\n        await ctx.db.delete(\"GroupTag\", tag._id);\n      }\n\n      await ctx.db.delete(\"Group\", id);\n    };\n\n    await deleteGroup(groupId);\n    return null;\n  },\n});\n\n// ============================================================================\n// Members\n// ============================================================================\n"],"mappings":"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"}

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

@@ -0,0 +1,217 @@
+declare namespace invites_d_exports {
+  export { inviteAccept, inviteAcceptByToken, inviteCreate, inviteGet, inviteGetByTokenHash, inviteList, inviteRevoke };
+}
+/**
+ * Create a new platform-level invitation. Optionally set `groupId` to tie
+ * the invite to a specific group. The invitation is sent to an email address
+ * and includes a hashed token for secure acceptance.
+ *
+ * Throws `ConvexError` with code `DUPLICATE_INVITE` when a pending invite
+ * already exists for the same email and scope:
+ * - group invite: same `email` + same `groupId`
+ * - platform invite: same `email` with no `groupId`
+ *
+ * When a duplicate check finds an existing invite that has passed its
+ * `expiresTime`, that invite is automatically marked as `"expired"` and the
+ * new invite is allowed through. CLI-generated invites (no email) skip
+ * duplicate detection entirely.
+ *
+ * @param args.groupId - Optional `Id<"Group">` to scope this invite to a specific group. Omit for a platform-wide invite.
+ * @param args.invitedByUserId - Optional `Id<"User">` of the user who issued the invitation.
+ * @param args.email - Optional email address of the invitee. When provided, duplicate detection is enforced.
+ * @param args.tokenHash - A pre-hashed token string used for secure, URL-safe invite acceptance.
+ * @param args.roleIds - Optional array of application-defined role identifiers to assign upon acceptance.
+ * @param args.status - The initial status of the invite (typically `"pending"`).
+ * @param args.expiresTime - Optional Unix timestamp (ms) after which the invite is considered expired.
+ * @param args.extend - Optional arbitrary payload for application-specific metadata.
+ * @returns The `Id<"GroupInvite">` of the newly created invite document.
+ *
+ * @example
+ * ```ts
+ * const inviteId = await ctx.runMutation(
+ *   components.auth.groups.inviteCreate,
+ *   {
+ *     groupId: teamGroupId,
+ *     invitedByUserId: currentUserId,
+ *     email: "alice@example.com",
+ *     tokenHash: hashedToken,
+ *     roleIds: ["editor"],
+ *     status: "pending",
+ *     expiresTime: Date.now() + 7 * 24 * 60 * 60 * 1000, // 7 days
+ *   },
+ * );
+ * ```
+ */
+declare const inviteCreate: any;
+/**
+ * Retrieve an invite by its document ID.
+ *
+ * Performs a direct lookup in the `GroupInvite` table and returns the full
+ * invite document, or `null` if no invite exists with the given ID.
+ *
+ * @param args.inviteId - The `Id<"GroupInvite">` of the invite to retrieve.
+ * @returns The invite document (including `email`, `status`, `groupId`, `tokenHash`, etc.) or `null` if not found.
+ *
+ * @example
+ * ```ts
+ * const invite = await ctx.runQuery(components.auth.groups.inviteGet, {
+ *   inviteId: existingInviteId,
+ * });
+ * if (invite !== null) {
+ *   console.log(invite.email, invite.status);
+ * }
+ * ```
+ */
+declare const inviteGet: any;
+/**
+ * Retrieve an invite by its hashed token.
+ *
+ * Looks up the `GroupInvite` table using the `token_hash` index. This is
+ * the primary mechanism for resolving an invite from a URL-embedded token.
+ * Returns `null` if no invite matches the given hash.
+ *
+ * @param args.tokenHash - The hashed token string to look up (must match the value stored at creation time).
+ * @returns The invite document or `null` if no invite exists with the given token hash.
+ *
+ * @example
+ * ```ts
+ * const invite = await ctx.runQuery(
+ *   components.auth.groups.inviteGetByTokenHash,
+ *   { tokenHash: "sha256_abc123..." },
+ * );
+ * if (invite !== null && invite.status === "pending") {
+ *   // proceed with acceptance flow
+ * }
+ * ```
+ */
+declare const inviteGetByTokenHash: any;
+/**
+ * List invites with optional filtering, sorting, and pagination.
+ *
+ * Returns `{ items, nextCursor }`. Supports filtering by `groupId`,
+ * `status`, `email`, `invitedByUserId`, `roleId`, `acceptedByUserId`, and
+ * `tokenHash`. The query engine automatically selects the best compound
+ * index based on the combination of filter fields provided. The `roleId`
+ * filter is applied in-memory after the index scan because role IDs are
+ * stored as an array.
+ *
+ * @param args.where - Optional filter criteria for narrowing results.
+ * @param args.where.tokenHash - Match invites with this exact hashed token.
+ * @param args.where.groupId - Match invites scoped to this group.
+ * @param args.where.status - Match invites with this status (e.g. `"pending"`, `"accepted"`, `"revoked"`).
+ * @param args.where.email - Match invites sent to this email address.
+ * @param args.where.invitedByUserId - Match invites created by this user.
+ * @param args.where.roleId - Match invites that include this role identifier in their `roleIds` array.
+ * @param args.where.acceptedByUserId - Match invites accepted by this specific user.
+ * @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"`, `"status"`, `"email"`, `"expiresTime"`, or `"acceptedTime"`.
+ * @param args.order - Sort direction: `"asc"` or `"desc"` (defaults to `"desc"`).
+ * @returns An object `{ items, nextCursor }` where `items` is an array of invite documents and `nextCursor` is `null` when there are no more pages.
+ *
+ * @example
+ * ```ts
+ * const { items, nextCursor } = await ctx.runQuery(
+ *   components.auth.groups.inviteList,
+ *   {
+ *     where: { groupId: teamGroupId, status: "pending" },
+ *     limit: 25,
+ *     order: "desc",
+ *   },
+ * );
+ * ```
+ */
+declare const inviteList: any;
+/**
+ * Accept a pending invitation.
+ *
+ * Marks the invite as `"accepted"` and records the acceptance timestamp.
+ * Throws a structured `ConvexError` when the invite doesn't exist or is not
+ * currently pending. If the invite has passed its `expiresTime`, it is
+ * automatically transitioned to `"expired"` and the acceptance is rejected.
+ *
+ * The caller is responsible for creating the corresponding member record
+ * (see {@link inviteAcceptByToken} for an all-in-one alternative that also
+ * handles membership).
+ *
+ * @param args.inviteId - The `Id<"GroupInvite">` of the invite to accept.
+ * @param args.acceptedByUserId - Optional `Id<"User">` of the user accepting the invite. Stored on the invite for audit purposes.
+ * @returns `null` on success.
+ * @throws `ConvexError` with code `INVITE_NOT_FOUND` if the invite does not exist.
+ * @throws `ConvexError` with code `INVITE_NOT_PENDING` if the invite has already been accepted, revoked, or otherwise finalized.
+ * @throws `ConvexError` with code `INVITE_EXPIRED` if the invite's `expiresTime` has passed.
+ *
+ * @example
+ * ```ts
+ * await ctx.runMutation(components.auth.groups.inviteAccept, {
+ *   inviteId: pendingInviteId,
+ *   acceptedByUserId: currentUserId,
+ * });
+ * ```
+ */
+declare const inviteAccept: any;
+/**
+ * Accept an invitation by raw token hash and atomically join group membership.
+ *
+ * This is the primary token-based acceptance flow. It looks up the invite by
+ * `tokenHash`, validates status and expiry, verifies the accepting user's
+ * email matches the invite email (when set), and — if the invite is scoped
+ * to a group — creates a `GroupMember` record in the same transaction.
+ *
+ * The operation is idempotent: if the invite was already accepted by the
+ * same user, it returns a result with `inviteStatus: "already_accepted"`
+ * and the existing membership information.
+ *
+ * @param args.tokenHash - The hashed token string that identifies the invite (typically extracted from an invite URL).
+ * @param args.acceptedByUserId - The `Id<"User">` of the user accepting the invitation. Their email must match the invite's email when one was specified.
+ * @returns An object describing the outcome:
+ *   - `inviteId` — the ID of the accepted invite.
+ *   - `groupId` — the group the invite targets, or `null` for platform invites.
+ *   - `memberId` — the ID of the created (or existing) member record, or `undefined` for platform invites.
+ *   - `inviteStatus` — `"accepted"` for a fresh acceptance, `"already_accepted"` for idempotent replays.
+ *   - `membershipStatus` — `"joined"`, `"already_joined"`, or `"not_applicable"`.
+ * @throws `ConvexError` with code `INVITE_NOT_FOUND` if no invite matches the token hash.
+ * @throws `ConvexError` with code `INVITE_EXPIRED` if the invite's `expiresTime` has passed.
+ * @throws `ConvexError` with code `INVITE_ALREADY_ACCEPTED` if the invite was accepted by a different user.
+ * @throws `ConvexError` with code `INVITE_NOT_PENDING` if the invite has been revoked or is in another non-pending state.
+ * @throws `ConvexError` with code `INVITE_EMAIL_MISMATCH` if the accepting user's email does not match the invite's email.
+ *
+ * @example
+ * ```ts
+ * const result = await ctx.runMutation(
+ *   components.auth.groups.inviteAcceptByToken,
+ *   {
+ *     tokenHash: "sha256_abc123...",
+ *     acceptedByUserId: currentUserId,
+ *   },
+ * );
+ * if (result.membershipStatus === "joined") {
+ *   console.log("Joined group", result.groupId, "as member", result.memberId);
+ * }
+ * ```
+ */
+declare const inviteAcceptByToken: any;
+/**
+ * Revoke a pending invitation.
+ *
+ * Marks the invite as `"revoked"`. Only invites with status `"pending"` can
+ * be revoked. Throws a structured `ConvexError` when the invite doesn't
+ * exist or is not currently pending. Once revoked, the invite's token can
+ * no longer be used for acceptance.
+ *
+ * @param args.inviteId - The `Id<"GroupInvite">` of the invite to revoke.
+ * @returns `null` on success.
+ * @throws `ConvexError` with code `INVITE_NOT_FOUND` if the invite does not exist.
+ * @throws `ConvexError` with code `INVITE_NOT_PENDING` if the invite has already been accepted, revoked, or expired.
+ *
+ * @example
+ * ```ts
+ * await ctx.runMutation(components.auth.groups.inviteRevoke, {
+ *   inviteId: pendingInviteId,
+ * });
+ * ```
+ */
+declare const inviteRevoke: any;
+//#endregion
+export { inviteAccept, inviteAcceptByToken, inviteCreate, inviteGet, inviteGetByTokenHash, inviteList, inviteRevoke, invites_d_exports };
+//# sourceMappingURL=invites.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"invites.d.ts","names":[],"sources":["../../../../src/component/public/groups/invites.ts"],"mappings":";;;;;;;;;;;;;;;AA8CA;;;;;AAiGA;;;;;AA6BA;;;;;AA+CA;;;;;AAmJA;;;;;AAkFA;;;;cAlZa,YAAA;AAohBb;;;;;;;;;;;;;;;;;;;AAAA,cAnba,SAAA;;;;;;;;;;;;;;;;;;;;;;cA6BA,oBAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;cA+CA,UAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;cAmJA,YAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;cAkFA,mBAAA;;;;;;;;;;;;;;;;;;;;;cAkIA,YAAA"}