@robelest/convex-auth 0.0.4-preview.18 → 0.0.4-preview.19

package/README.md

@@ -36,9 +36,12 @@ bun add @robelest/convex-auth
 Before running setup:
 
 - Run from your app project root (must include `package.json`).
-- Make sure a Convex deployment can be resolved. By default the CLI reads
-  `CONVEX_DEPLOYMENT` (usually set by `npx convex dev`), or you can pass
-  `--prod`, `--preview-name`, `--deployment-name`, `--url`, or `--admin-key`.
+- Make sure a Convex deployment can be resolved. By default the CLI reads a
+  typed `CONVEX_DEPLOYMENT` like `dev:my-deployment` (usually set by
+  `npx convex dev`), or you can pass `--prod`, `--preview-name`,
+  `--deployment-name`, `--url`, or `--admin-key`.
+- Use `--url` for explicit or self-hosted targets. Typed deployment and
+  admin-key parsing only applies to Convex Cloud selections.
 
 ```bash
 bunx @robelest/convex-auth

package/dist/authorization/index.d.ts

@@ -4,6 +4,52 @@
  *
  * @module
  */
+/**
+ * Define typed role definitions for authorization.
+ *
+ * Transforms a declarative roles configuration object into a normalized
+ * map where each role has an `id` (matching its key), an optional `label`,
+ * and a typed `grants` array. The returned object is fully type-safe:
+ * role IDs and grant strings are narrowed to their literal types, so
+ * `member.resolve()` and `member.create()` calls are checked at compile time.
+ * This is the canonical way to define role metadata for the auth library.
+ *
+ * @param roles - An object mapping role IDs to their configuration.
+ *   Each entry must include a `grants` array of permission strings and
+ *   may include an optional human-readable `label`.
+ * @typeParam TRoles - The object literal shape of your role definitions.
+ * @returns An object with the same keys as `roles`, where each value
+ *   is `{ id, label?, grants }` — `id` is the role key as a string,
+ *   and `grants` is a mutable array of the declared grant strings.
+ *
+ * @example
+ * ```ts
+ * import { defineRoles } from "@robelest/convex-auth/authorization";
+ *
+ * const roles = defineRoles({
+ *   admin: { label: "Administrator", grants: ["issues:write", "members:manage"] },
+ *   member: { label: "Member", grants: ["issues:write"] },
+ *   viewer: { grants: ["issues:read"] },
+ * });
+ *
+ * // roles.admin.id   === "admin"
+ * // roles.admin.grants === ["issues:write", "members:manage"]
+ *
+ * // Pass to createAuth:
+ * const auth = createAuth(components.auth, {
+ *   providers: [...],
+ *   authorization: { roles },
+ * });
+ * ```
+ *
+ * @example
+ * ```ts
+ * type RoleId = keyof typeof roles;
+ * // RoleId = "admin" | "member" | "viewer"
+ * ```
+ *
+ * @see {@link ConvexAuthConfig}
+ */
 declare function defineRoles<const TRoles extends Record<string, {
   label?: string;
   grants: readonly string[];

package/dist/authorization/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","names":[],"sources":["../../src/authorization/index.ts"],"mappings":";;AAMA;;;;iBAAgB,WAAA,sBACO,MAAA;EAEjB,KAAA;EAAgB,MAAA;AAAA,GAAA,CAGpB,KAAA,EAAO,MAAA,iBAEK,MAAA;EACV,EAAA,EAAI,CAAA;EACJ,KAAA,GAAQ,MAAA,CAAO,CAAA;EACf,MAAA,EAAQ,KAAA,CAAM,MAAA,CAAO,CAAA;AAAA"}
+{"version":3,"file":"index.d.ts","names":[],"sources":["../../src/authorization/index.ts"],"mappings":";;AAoDA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAAgB,WAAA,sBACO,MAAA;EAEjB,KAAA;EAAgB,MAAA;AAAA,GAAA,CAGpB,KAAA,EAAO,MAAA,iBAEK,MAAA;EACV,EAAA,EAAI,CAAA;EACJ,KAAA,GAAQ,MAAA,CAAO,CAAA;EACf,MAAA,EAAQ,KAAA,CAAM,MAAA,CAAO,CAAA;AAAA"}

package/dist/authorization/index.js

@@ -4,6 +4,52 @@
 *
 * @module
 */
+/**
+* Define typed role definitions for authorization.
+*
+* Transforms a declarative roles configuration object into a normalized
+* map where each role has an `id` (matching its key), an optional `label`,
+* and a typed `grants` array. The returned object is fully type-safe:
+* role IDs and grant strings are narrowed to their literal types, so
+* `member.resolve()` and `member.create()` calls are checked at compile time.
+* This is the canonical way to define role metadata for the auth library.
+*
+* @param roles - An object mapping role IDs to their configuration.
+*   Each entry must include a `grants` array of permission strings and
+*   may include an optional human-readable `label`.
+* @typeParam TRoles - The object literal shape of your role definitions.
+* @returns An object with the same keys as `roles`, where each value
+*   is `{ id, label?, grants }` — `id` is the role key as a string,
+*   and `grants` is a mutable array of the declared grant strings.
+*
+* @example
+* ```ts
+* import { defineRoles } from "@robelest/convex-auth/authorization";
+*
+* const roles = defineRoles({
+*   admin: { label: "Administrator", grants: ["issues:write", "members:manage"] },
+*   member: { label: "Member", grants: ["issues:write"] },
+*   viewer: { grants: ["issues:read"] },
+* });
+*
+* // roles.admin.id   === "admin"
+* // roles.admin.grants === ["issues:write", "members:manage"]
+*
+* // Pass to createAuth:
+* const auth = createAuth(components.auth, {
+*   providers: [...],
+*   authorization: { roles },
+* });
+* ```
+*
+* @example
+* ```ts
+* type RoleId = keyof typeof roles;
+* // RoleId = "admin" | "member" | "viewer"
+* ```
+*
+* @see {@link ConvexAuthConfig}
+*/
 function defineRoles(roles) {
 	return Object.fromEntries(Object.entries(roles).map(([id, role]) => [id, {
 		id,

package/dist/authorization/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","names":[],"sources":["../../src/authorization/index.ts"],"sourcesContent":["/**\n * Lightweight authorization helpers.\n *\n * @module\n */\n\nexport function defineRoles<\n  const TRoles extends Record<\n    string,\n    { label?: string; grants: readonly string[] }\n  >,\n>(\n  roles: TRoles,\n): {\n  [K in keyof TRoles]: {\n    id: K & string;\n    label?: TRoles[K][\"label\"];\n    grants: Array<TRoles[K][\"grants\"][number] & string>;\n  };\n} {\n  return Object.fromEntries(\n    Object.entries(roles).map(([id, role]) => [\n      id,\n      {\n        id,\n        ...(role.label ? { label: role.label } : {}),\n        grants: [...role.grants],\n      },\n    ]),\n  ) as {\n    [K in keyof TRoles]: {\n      id: K & string;\n      label?: TRoles[K][\"label\"];\n      grants: Array<TRoles[K][\"grants\"][number] & string>;\n    };\n  };\n}\n"],"mappings":";;;;;;AAMA,SAAgB,YAMd,OAOA;AACA,QAAO,OAAO,YACZ,OAAO,QAAQ,MAAM,CAAC,KAAK,CAAC,IAAI,UAAU,CACxC,IACA;EACE;EACA,GAAI,KAAK,QAAQ,EAAE,OAAO,KAAK,OAAO,GAAG,EAAE;EAC3C,QAAQ,CAAC,GAAG,KAAK,OAAO;EACzB,CACF,CAAC,CACH"}
+{"version":3,"file":"index.js","names":[],"sources":["../../src/authorization/index.ts"],"sourcesContent":["/**\n * Lightweight authorization helpers.\n *\n * @module\n */\n\n/**\n * Define typed role definitions for authorization.\n *\n * Transforms a declarative roles configuration object into a normalized\n * map where each role has an `id` (matching its key), an optional `label`,\n * and a typed `grants` array. The returned object is fully type-safe:\n * role IDs and grant strings are narrowed to their literal types, so\n * `member.resolve()` and `member.create()` calls are checked at compile time.\n * This is the canonical way to define role metadata for the auth library.\n *\n * @param roles - An object mapping role IDs to their configuration.\n *   Each entry must include a `grants` array of permission strings and\n *   may include an optional human-readable `label`.\n * @typeParam TRoles - The object literal shape of your role definitions.\n * @returns An object with the same keys as `roles`, where each value\n *   is `{ id, label?, grants }` — `id` is the role key as a string,\n *   and `grants` is a mutable array of the declared grant strings.\n *\n * @example\n * ```ts\n * import { defineRoles } from \"@robelest/convex-auth/authorization\";\n *\n * const roles = defineRoles({\n *   admin: { label: \"Administrator\", grants: [\"issues:write\", \"members:manage\"] },\n *   member: { label: \"Member\", grants: [\"issues:write\"] },\n *   viewer: { grants: [\"issues:read\"] },\n * });\n *\n * // roles.admin.id   === \"admin\"\n * // roles.admin.grants === [\"issues:write\", \"members:manage\"]\n *\n * // Pass to createAuth:\n * const auth = createAuth(components.auth, {\n *   providers: [...],\n *   authorization: { roles },\n * });\n * ```\n *\n * @example\n * ```ts\n * type RoleId = keyof typeof roles;\n * // RoleId = \"admin\" | \"member\" | \"viewer\"\n * ```\n *\n * @see {@link ConvexAuthConfig}\n */\nexport function defineRoles<\n  const TRoles extends Record<\n    string,\n    { label?: string; grants: readonly string[] }\n  >,\n>(\n  roles: TRoles,\n): {\n  [K in keyof TRoles]: {\n    id: K & string;\n    label?: TRoles[K][\"label\"];\n    grants: Array<TRoles[K][\"grants\"][number] & string>;\n  };\n} {\n  return Object.fromEntries(\n    Object.entries(roles).map(([id, role]) => [\n      id,\n      {\n        id,\n        ...(role.label ? { label: role.label } : {}),\n        grants: [...role.grants],\n      },\n    ]),\n  ) as {\n    [K in keyof TRoles]: {\n      id: K & string;\n      label?: TRoles[K][\"label\"];\n      grants: Array<TRoles[K][\"grants\"][number] & string>;\n    };\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAoDA,SAAgB,YAMd,OAOA;AACA,QAAO,OAAO,YACZ,OAAO,QAAQ,MAAM,CAAC,KAAK,CAAC,IAAI,UAAU,CACxC,IACA;EACE;EACA,GAAI,KAAK,QAAQ,EAAE,OAAO,KAAK,OAAO,GAAG,EAAE;EAC3C,QAAQ,CAAC,GAAG,KAAK,OAAO;EACzB,CACF,CAAC,CACH"}

package/dist/bin.cjs

@@ -6043,13 +6043,14 @@ function readConvexJson() {
 }
 function readConvexDeployment(options) {
 	const { adminKey, url, prod, previewName, deploymentName } = options;
+	if (url) return {
+		name: url,
+		type: null,
+		options
+	};
 	const adminKeyName = adminKey ? deploymentNameFromAdminKey(adminKey) : null;
 	const adminKeyType = adminKey ? deploymentTypeFromAdminKey(adminKey) : null;
 	const explicitSelection = [
-		url ? {
-			name: adminKeyName ?? url,
-			type: adminKeyType
-		} : null,
 		prod ? {
 			name: adminKeyName,
 			type: "prod"
@@ -6073,27 +6074,34 @@ function readConvexDeployment(options) {
 	};
 	(0, import_main.config)({ path: ".env.local" });
 	(0, import_main.config)();
-	if (process.env.CONVEX_DEPLOYMENT) return {
-		name: stripDeploymentTypePrefix(process.env.CONVEX_DEPLOYMENT),
-		type: getDeploymentTypeFromConfiguredDeployment(process.env.CONVEX_DEPLOYMENT),
-		options
-	};
+	if (process.env.CONVEX_DEPLOYMENT) {
+		const type = getDeploymentTypeFromConfiguredDeployment(process.env.CONVEX_DEPLOYMENT);
+		return {
+			name: stripDeploymentTypePrefix(process.env.CONVEX_DEPLOYMENT),
+			type,
+			options
+		};
+	}
 	logErrorAndExit("Could not find a configured CONVEX_DEPLOYMENT. Did you forget to run `npx convex dev` first?");
 }
 function stripDeploymentTypePrefix(deployment) {
-	return deployment.split(":").at(-1);
+	const [type, name] = deployment.split(":");
+	if (type !== "prod" && type !== "dev" && type !== "preview" || !name) logErrorAndExit("Invalid CONVEX_DEPLOYMENT.", "Expected a typed deployment like \"dev:my-deployment\", \"prod:my-deployment\", or \"preview:my-deployment\".");
+	return name;
 }
 function getDeploymentTypeFromConfiguredDeployment(raw) {
 	const typeRaw = raw.split(":")[0];
-	return typeRaw === "prod" || typeRaw === "dev" || typeRaw === "preview" ? typeRaw : null;
+	if (typeRaw === "prod" || typeRaw === "dev" || typeRaw === "preview") return typeRaw;
+	logErrorAndExit("Invalid CONVEX_DEPLOYMENT.", "Expected a typed deployment like \"dev:my-deployment\", \"prod:my-deployment\", or \"preview:my-deployment\".");
 }
 function deploymentNameFromAdminKey(adminKey) {
 	const parts = adminKey.split("|");
 	return parts.length > 1 && !isPreviewDeployKey(adminKey) ? stripDeploymentTypePrefix(parts[0]) : null;
 }
 function deploymentTypeFromAdminKey(adminKey) {
-	const parts = adminKey.split(":");
-	return parts.length > 1 ? parts.at(0) : null;
+	const type = adminKey.split(":")[0];
+	if (type === "prod" || type === "dev" || type === "preview") return type;
+	logErrorAndExit("Invalid admin key.", "Expected a typed key like \"dev:deployment|...\", \"prod:deployment|...\", or \"preview:...\".");
 }
 function isPreviewDeployKey(adminKey) {
 	const parts = adminKey.split("|");

package/dist/client/core/types.d.ts

@@ -0,0 +1,20 @@
+import { FunctionReference } from "convex/server";
+import { ConvexError, Value } from "convex/values";
+
+//#region src/client/core/types.d.ts
+/**
+ * Typed Convex API references for the auth functions.
+ * Pass these from your generated `api` object.
+ *
+ * @typeParam HasPasskey - Whether the passkey provider is configured.
+ * @typeParam HasTotp - Whether the TOTP provider is configured.
+ * @typeParam HasDevice - Whether the device provider is configured.
+ */
+type AuthApiRefs<HasPasskey extends boolean = boolean, HasTotp extends boolean = boolean, HasDevice extends boolean = boolean> = {
+  signIn: FunctionReference<"action", "public", any, any>;
+  signOut: FunctionReference<"action", "public", any, any>;
+  store: FunctionReference<"mutation", "public", any, any>;
+};
+//#endregion
+export { AuthApiRefs };
+//# sourceMappingURL=types.d.ts.map

package/dist/client/core/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","names":[],"sources":["../../../src/client/core/types.ts"],"mappings":";;;;;;;;;;;;KA2HY,WAAA;EAKV,MAAA,EAAQ,iBAAA;EACR,OAAA,EAAS,iBAAA;EACT,KAAA,EAAO,iBAAA;AAAA"}

package/dist/client/index.d.ts

@@ -1,16 +1,2 @@
-import { AUTH_ERRORS, AuthErrorCode, isAuthError, parseAuthError } from "../server/errors.js";
-import { FunctionReference } from "convex/server";
-
-//#region src/client/index.d.ts
-/**
- * Typed Convex API references for the auth functions.
- * Pass these from your generated `api` object.
- */
-type AuthApiRefs<HasPasskey extends boolean = boolean, HasTotp extends boolean = boolean, HasDevice extends boolean = boolean> = {
-  signIn: FunctionReference<"action", "public", any, any>;
-  signOut: FunctionReference<"action", "public", any, any>;
-  store: FunctionReference<"mutation", "public", any, any>;
-};
-//#endregion
-export { AuthApiRefs };
-//# sourceMappingURL=index.d.ts.map
+import { AuthApiRefs } from "./core/types.js";
+import { AUTH_ERRORS, AuthErrorCode, isAuthError, parseAuthError } from "../server/errors.js";

package/dist/client/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","names":[],"sources":["../../src/client/index.ts"],"mappings":";;;;;;;;KA6HY,WAAA;EAKV,MAAA,EAAQ,iBAAA;EACR,OAAA,EAAS,iBAAA;EACT,KAAA,EAAO,iBAAA;AAAA"}
+{"version":3,"file":"index.d.ts","names":[],"sources":["../../src/client/index.ts"],"mappings":";;;;;AAwHA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAAgB,MAAA,aACF,WAAA,8BAAyC,WAAA,CAAA,CACrD,OAAA,EAAS,aAAA,CAAc,GAAA,IAAO,UAAA,CAAW,GAAA"}