@molecule/api-resource-user 1.0.0

package/dist/schema.js

@@ -0,0 +1,229 @@
+/**
+ * User resource schema definitions using Zod.
+ *
+ * Types are automatically inferred from schemas using z.infer<>.
+ *
+ * @module
+ */
+import { z } from 'zod';
+import { basePropsSchema } from '@molecule/api-resource/schema';
+/**
+ * Maximum length (in characters) of a user's `bio`.
+ */
+export const MAX_BIO_LENGTH = 1000;
+/**
+ * Maximum length (in characters) of a user's `avatar`. Sized to permit a small
+ * inline data-URI (~256KB) without requiring an external upload/storage bond.
+ * Larger avatars must be hosted elsewhere and referenced by URL.
+ */
+export const MAX_AVATAR_LENGTH = 256 * 1024;
+/**
+ * Creates a full schema for user props.
+ *
+ * OAuth servers and plan keys can be constrained by passing them as options.
+ * @param options - Optional configuration.
+ * @param options.oauthServers - Tuple of allowed OAuth server names. Constrains `oauthServer` to a Zod enum.
+ * @param options.planKeys - Tuple of allowed plan key strings. Constrains `planKey` to a Zod enum.
+ * @returns A Zod object schema extending `basePropsSchema` with user-specific fields (username, email, OAuth, plan).
+ */
+export const createSchema = (options) => {
+    return basePropsSchema.extend({
+        /**
+         * An alphanumeric username.
+         */
+        username: z.string().optional(),
+        /**
+         * The user's given name.
+         */
+        name: z.string().optional(),
+        /**
+         * The user's email address.
+         */
+        email: z.string().email().nullable().optional(),
+        /**
+         * Whether the user's email address has been verified — either by an OAuth
+         * provider that affirmatively confirmed mailbox ownership (Google/Apple
+         * `email_verified`, GitHub public email, GitLab `confirmed_at`) or by a
+         * post-signup email-confirmation flow. Defaults to `false`. Used to decide
+         * whether a provider-supplied email may be trusted over an existing,
+         * unverified account so an unverified squatter cannot block the verified
+         * mailbox owner.
+         */
+        emailVerified: z.boolean().optional(),
+        /**
+         * The user's avatar — either a URL or a small inline data-URI
+         * (capped at {@link MAX_AVATAR_LENGTH} characters / ~256KB). Optional and
+         * nullable so it can be cleared and remains back-compatible with existing rows.
+         */
+        avatar: z.string().max(MAX_AVATAR_LENGTH).nullable().optional(),
+        /**
+         * A short free-text biography for the user
+         * (capped at {@link MAX_BIO_LENGTH} characters). Optional and nullable for
+         * back-compat and clearing.
+         */
+        bio: z.string().max(MAX_BIO_LENGTH).nullable().optional(),
+        /**
+         * Whether two-factor authentication is enabled.
+         */
+        twoFactorEnabled: z.boolean().optional(),
+        /**
+         * The OAuth server used to authenticate the user.
+         */
+        oauthServer: options?.oauthServers
+            ? z.enum(options.oauthServers).optional()
+            : z.string().optional(),
+        /**
+         * Unique identifier for the user from the OAuth server.
+         */
+        oauthId: z.string().optional(),
+        /**
+         * User data retrieved from the OAuth server.
+         */
+        oauthData: z.record(z.string(), z.unknown()).optional(),
+        /**
+         * The user's current plan key.
+         */
+        planKey: options?.planKeys ? z.enum(options.planKeys).optional() : z.string().optional(),
+        /**
+         * When the plan expires (ISO 8601 timestamp).
+         */
+        planExpiresAt: z.string().datetime().optional(),
+        /**
+         * True if the plan will automatically renew.
+         */
+        planAutoRenews: z.boolean().optional(),
+    });
+};
+/**
+ * Default schema for user props.
+ */
+export const propsSchema = createSchema();
+/**
+ * Secret properties stored in a separate table.
+ */
+export const secretPropsSchema = z.object({
+    /**
+     * The user's ID.
+     */
+    id: z.string().uuid(),
+    /**
+     * The user's hashed password.
+     */
+    passwordHash: z.string().optional(),
+    /**
+     * Token for password reset.
+     */
+    passwordResetToken: z.string().optional(),
+    /**
+     * When the password reset token was created.
+     */
+    passwordResetTokenAt: z.string().datetime().optional(),
+    /**
+     * Pending two-factor secret during setup.
+     */
+    pendingTwoFactorSecret: z.string().optional(),
+    /**
+     * Active two-factor secret.
+     */
+    twoFactorSecret: z.string().optional(),
+    /**
+     * The last successfully-consumed TOTP time step (RFC 6238 time step counter).
+     * Persisted after each successful 2FA verification and passed back as
+     * `afterTimeStep` so the same (or an earlier) code is rejected within its
+     * validity window — single-use / replay protection.
+     */
+    lastTwoFactorTimeStep: z.number().int().optional(),
+});
+/**
+ * Schema for creating a user via password.
+ */
+export const createPropsSchema = propsSchema.pick({
+    username: true,
+    name: true,
+    email: true,
+});
+/** Schema for creating secret props (password hash only). */
+export const createSecretPropsSchema = secretPropsSchema.pick({
+    passwordHash: true,
+});
+/**
+ * Schema for creating a user via OAuth.
+ */
+export const createOAuthPropsSchema = propsSchema.pick({
+    username: true,
+    name: true,
+    email: true,
+    emailVerified: true,
+    oauthServer: true,
+    oauthId: true,
+    oauthData: true,
+});
+/** Schema for updating a user (partial username, name, email, avatar, bio). */
+export const updatePropsSchema = propsSchema
+    .pick({
+    username: true,
+    name: true,
+    email: true,
+    avatar: true,
+    bio: true,
+})
+    .partial();
+/** Schema for updating password secret props (partial password hash). */
+export const updatePasswordSecretPropsSchema = secretPropsSchema
+    .pick({
+    passwordHash: true,
+})
+    .partial();
+/** Schema for updating a user's plan (partial planKey, planExpiresAt, planAutoRenews). */
+export const updatePlanPropsSchema = propsSchema
+    .pick({
+    planKey: true,
+    planExpiresAt: true,
+    planAutoRenews: true,
+})
+    .partial();
+/**
+ * Schema for verifying two-factor authentication.
+ */
+export const verifyTwoFactorPropsSchema = propsSchema
+    .pick({
+    twoFactorEnabled: true,
+})
+    .partial();
+/**
+ * Schema for two-factor secret props.
+ */
+export const verifyTwoFactorSecretPropsSchema = secretPropsSchema
+    .pick({
+    pendingTwoFactorSecret: true,
+    twoFactorSecret: true,
+})
+    .partial();
+/** Zod schema for JWT session payloads (userId, deviceId, optional OAuth fields). */
+export const sessionSchema = z.object({
+    /**
+     * The session ID (required for web browser clients).
+     */
+    id: z.string().optional(),
+    /**
+     * The user ID.
+     */
+    userId: z.string(),
+    /**
+     * The device ID.
+     */
+    deviceId: z.string(),
+    /**
+     * The OAuth server if logged in via OAuth.
+     */
+    oauthServer: z.string().optional(),
+    /**
+     * The OAuth ID if logged in via OAuth.
+     */
+    oauthId: z.string().optional(),
+});
+/**
+ * Re-export zod for convenience.
+ */
+export { z };
+//# sourceMappingURL=schema.js.map

package/dist/schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.js","sourceRoot":"","sources":["../src/schema.ts"],"names":[],"mappings":"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"}

package/dist/secrets.d.ts

@@ -0,0 +1,16 @@
+/**
+ * User resource secret definitions — self-registered at import time so the
+ * runtime secrets registry (`@molecule/api-secrets`) can drive boot-time
+ * configuration reports and actionable "not configured" errors.
+ *
+ * Content is derived MECHANICALLY from this package's mlcl registry secrets
+ * entry (label/instructions/setupUrl/example) via the fleet formula, so
+ * packages sharing a key register byte-identical definitions and
+ * registration order never matters.
+ *
+ * @module
+ */
+import type { SecretDefinition } from '@molecule/api-secrets';
+/** Secret definitions required by the user resource. */
+export declare const resourceUserSecretDefinitions: SecretDefinition[];
+//# sourceMappingURL=secrets.d.ts.map

package/dist/secrets.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"secrets.d.ts","sourceRoot":"","sources":["../src/secrets.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAA;AAG7D,wDAAwD;AACxD,eAAO,MAAM,6BAA6B,EAAE,gBAAgB,EAa3D,CAAA"}

package/dist/secrets.js

@@ -0,0 +1,28 @@
+/**
+ * User resource secret definitions — self-registered at import time so the
+ * runtime secrets registry (`@molecule/api-secrets`) can drive boot-time
+ * configuration reports and actionable "not configured" errors.
+ *
+ * Content is derived MECHANICALLY from this package's mlcl registry secrets
+ * entry (label/instructions/setupUrl/example) via the fleet formula, so
+ * packages sharing a key register byte-identical definitions and
+ * registration order never matters.
+ *
+ * @module
+ */
+import { registerSecrets } from '@molecule/api-secrets';
+/** Secret definitions required by the user resource. */
+export const resourceUserSecretDefinitions = [
+    {
+        key: 'JWT_PRIVATE_KEY',
+        description: 'JWT signing key (RSA private) — RSA private key (PEM) for signing JWTs; @molecule/api-jwt also self-generates key files on first boot if unset. Auto-generated at scaffold — no manual setup needed.',
+        required: true,
+    },
+    {
+        key: 'JWT_PUBLIC_KEY',
+        description: 'JWT verification key (RSA public) — RSA public key (PEM) matching JWT_PRIVATE_KEY. Auto-generated at scaffold — no manual setup needed.',
+        required: true,
+    },
+];
+registerSecrets(resourceUserSecretDefinitions);
+//# sourceMappingURL=secrets.js.map

package/dist/secrets.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"secrets.js","sourceRoot":"","sources":["../src/secrets.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAGH,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAA;AAEvD,wDAAwD;AACxD,MAAM,CAAC,MAAM,6BAA6B,GAAuB;IAC/D;QACE,GAAG,EAAE,iBAAiB;QACtB,WAAW,EACT,sMAAsM;QACxM,QAAQ,EAAE,IAAI;KACf;IACD;QACE,GAAG,EAAE,gBAAgB;QACrB,WAAW,EACT,yIAAyI;QAC3I,QAAQ,EAAE,IAAI;KACf;CACF,CAAA;AAED,eAAe,CAAC,6BAA6B,CAAC,CAAA"}

package/dist/types.d.ts

@@ -0,0 +1,14 @@
+/**
+ * User type definitions.
+ *
+ * Types are inferred from Zod schemas in schema.ts.
+ *
+ * @module
+ */
+import type * as resourceTypes from '@molecule/api-resource/types';
+export type { CreateOAuthProps, CreateProps, CreateSecretProps, Props, SecretProps, Session, UpdatePasswordSecretProps, UpdatePlanProps, UpdateProps, VerifyTwoFactorProps, VerifyTwoFactorSecretProps, } from './schema.js';
+/**
+ * An object describing the `user` resource.
+ */
+export type Resource<T = unknown> = resourceTypes.Resource<T>;
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,KAAK,aAAa,MAAM,8BAA8B,CAAA;AAGlE,YAAY,EACV,gBAAgB,EAChB,WAAW,EACX,iBAAiB,EACjB,KAAK,EACL,WAAW,EACX,OAAO,EACP,yBAAyB,EACzB,eAAe,EACf,WAAW,EACX,oBAAoB,EACpB,0BAA0B,GAC3B,MAAM,aAAa,CAAA;AAEpB;;GAEG;AACH,MAAM,MAAM,QAAQ,CAAC,CAAC,GAAG,OAAO,IAAI,aAAa,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAA"}

package/dist/types.js

@@ -0,0 +1,9 @@
+/**
+ * User type definitions.
+ *
+ * Types are inferred from Zod schemas in schema.ts.
+ *
+ * @module
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG"}

package/dist/utilities/getPlan.d.ts

@@ -0,0 +1,19 @@
+import type { Plan } from '@molecule/api-payments';
+import type * as types from '../types.js';
+/**
+ * Extended plan info returned by getPlan, including expiration and renewal status.
+ */
+interface PlanInfo extends Plan {
+    isExpired: boolean;
+    expiresAt: string | undefined;
+    autoRenews: boolean | undefined;
+}
+/**
+ * Get a user's current plan info.
+ * Uses the bonded PlanService if available.
+ * @param user - The user props (needs `planKey`, `planExpiresAt`, `planAutoRenews`).
+ * @returns The user's plan info with expiration status, or `null` if no `PlanService` is bonded.
+ */
+export declare const getPlan: (user: types.Props) => Promise<PlanInfo | Plan | null>;
+export {};
+//# sourceMappingURL=getPlan.d.ts.map

package/dist/utilities/getPlan.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"getPlan.d.ts","sourceRoot":"","sources":["../../src/utilities/getPlan.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,IAAI,EAAe,MAAM,wBAAwB,CAAA;AAE/D,OAAO,KAAK,KAAK,KAAK,MAAM,aAAa,CAAA;AAEzC;;GAEG;AACH,UAAU,QAAS,SAAQ,IAAI;IAC7B,SAAS,EAAE,OAAO,CAAA;IAClB,SAAS,EAAE,MAAM,GAAG,SAAS,CAAA;IAC7B,UAAU,EAAE,OAAO,GAAG,SAAS,CAAA;CAChC;AAED;;;;;GAKG;AACH,eAAO,MAAM,OAAO,GAAU,MAAM,KAAK,CAAC,KAAK,KAAG,OAAO,CAAC,QAAQ,GAAG,IAAI,GAAG,IAAI,CAoB/E,CAAA"}

package/dist/utilities/getPlan.js

@@ -0,0 +1,26 @@
+import { get } from '@molecule/api-bond';
+/**
+ * Get a user's current plan info.
+ * Uses the bonded PlanService if available.
+ * @param user - The user props (needs `planKey`, `planExpiresAt`, `planAutoRenews`).
+ * @returns The user's plan info with expiration status, or `null` if no `PlanService` is bonded.
+ */
+export const getPlan = async (user) => {
+    const plans = get('plans');
+    if (!plans)
+        return null;
+    const plan = plans.findPlan(user.planKey || '');
+    if (plan) {
+        const isExpired = user.planExpiresAt
+            ? new Date(user.planExpiresAt).getTime() < Date.now()
+            : false;
+        return {
+            ...plan,
+            isExpired,
+            expiresAt: user.planExpiresAt,
+            autoRenews: user.planAutoRenews,
+        };
+    }
+    return plans.getDefaultPlan();
+};
+//# sourceMappingURL=getPlan.js.map

package/dist/utilities/getPlan.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"getPlan.js","sourceRoot":"","sources":["../../src/utilities/getPlan.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,GAAG,EAAE,MAAM,oBAAoB,CAAA;AAcxC;;;;;GAKG;AACH,MAAM,CAAC,MAAM,OAAO,GAAG,KAAK,EAAE,IAAiB,EAAmC,EAAE;IAClF,MAAM,KAAK,GAAG,GAAG,CAAc,OAAO,CAAC,CAAA;IACvC,IAAI,CAAC,KAAK;QAAE,OAAO,IAAI,CAAA;IAEvB,MAAM,IAAI,GAAG,KAAK,CAAC,QAAQ,CAAC,IAAI,CAAC,OAAO,IAAI,EAAE,CAAC,CAAA;IAE/C,IAAI,IAAI,EAAE,CAAC;QACT,MAAM,SAAS,GAAG,IAAI,CAAC,aAAa;YAClC,CAAC,CAAC,IAAI,IAAI,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC,OAAO,EAAE,GAAG,IAAI,CAAC,GAAG,EAAE;YACrD,CAAC,CAAC,KAAK,CAAA;QAET,OAAO;YACL,GAAG,IAAI;YACP,SAAS;YACT,SAAS,EAAE,IAAI,CAAC,aAAa;YAC7B,UAAU,EAAE,IAAI,CAAC,cAAc;SAChC,CAAA;IACH,CAAC;IAED,OAAO,KAAK,CAAC,cAAc,EAAE,CAAA;AAC/B,CAAC,CAAA"}

package/dist/utilities/hashResetToken.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Hash a password-reset token for storage/lookup.
+ *
+ * The token emailed to the user is high-entropy random, but storing it VERBATIM
+ * in `usersSecrets.passwordResetToken` means any read of that table (a backup, a
+ * replica, the shared control-plane cluster) yields a live account-takeover
+ * credential. Store `sha256(token)` instead and compare digests: a DB reader
+ * gets only the hash, which cannot be replayed against the reset endpoint. The
+ * token itself is single-use with a short TTL, so a fast hash (no salt) is
+ * sufficient — this is not a password.
+ *
+ * @param token - The raw reset token (as generated / as received from the user).
+ * @returns The lowercase hex SHA-256 digest to store and compare.
+ */
+export declare function hashResetToken(token: string): string;
+//# sourceMappingURL=hashResetToken.d.ts.map

package/dist/utilities/hashResetToken.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hashResetToken.d.ts","sourceRoot":"","sources":["../../src/utilities/hashResetToken.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;GAaG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEpD"}

package/dist/utilities/hashResetToken.js

@@ -0,0 +1,19 @@
+import { createHash } from 'node:crypto';
+/**
+ * Hash a password-reset token for storage/lookup.
+ *
+ * The token emailed to the user is high-entropy random, but storing it VERBATIM
+ * in `usersSecrets.passwordResetToken` means any read of that table (a backup, a
+ * replica, the shared control-plane cluster) yields a live account-takeover
+ * credential. Store `sha256(token)` instead and compare digests: a DB reader
+ * gets only the hash, which cannot be replayed against the reset endpoint. The
+ * token itself is single-use with a short TTL, so a fast hash (no salt) is
+ * sufficient — this is not a password.
+ *
+ * @param token - The raw reset token (as generated / as received from the user).
+ * @returns The lowercase hex SHA-256 digest to store and compare.
+ */
+export function hashResetToken(token) {
+    return createHash('sha256').update(token).digest('hex');
+}
+//# sourceMappingURL=hashResetToken.js.map

package/dist/utilities/hashResetToken.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hashResetToken.js","sourceRoot":"","sources":["../../src/utilities/hashResetToken.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AAExC;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,cAAc,CAAC,KAAa;IAC1C,OAAO,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAA;AACzD,CAAC"}

package/dist/utilities/index.d.ts

@@ -0,0 +1,5 @@
+export * from './getPlan.js';
+export * from './invalidateEntitlements.js';
+export * from './normalizeEmail.js';
+export * from './notify.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/utilities/index.ts"],"names":[],"mappings":"AAAA,cAAc,cAAc,CAAA;AAC5B,cAAc,6BAA6B,CAAA;AAC3C,cAAc,qBAAqB,CAAA;AACnC,cAAc,aAAa,CAAA"}

package/dist/utilities/index.js

@@ -0,0 +1,5 @@
+export * from './getPlan.js';
+export * from './invalidateEntitlements.js';
+export * from './normalizeEmail.js';
+export * from './notify.js';
+//# sourceMappingURL=index.js.map

package/dist/utilities/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/utilities/index.ts"],"names":[],"mappings":"AAAA,cAAc,cAAc,CAAA;AAC5B,cAAc,6BAA6B,CAAA;AAC3C,cAAc,qBAAqB,CAAA;AACnC,cAAc,aAAa,CAAA"}

package/dist/utilities/invalidateEntitlements.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Invalidates the entitlements plan-key cache for a user after their plan
+ * changed (paid upgrade via `verifyPayment`, webhook grant/cancellation via
+ * `handlePaymentNotification`, admin `updatePlan`).
+ *
+ * `@molecule/api-entitlements` caches each user's effective plan key for its
+ * TTL (default 5 minutes) on the `getEffectiveTier` hot path. Without this
+ * call, a user who just PAID keeps seeing their old (free) tier — and a
+ * canceled user keeps premium — until the TTL lapses. The dependency is an
+ * OPTIONAL peer: apps that don't use entitlements simply have nothing to
+ * invalidate, so the import failure is a documented no-op.
+ *
+ * @param userId - The user whose cached plan key must be dropped.
+ */
+export declare const invalidateEntitlementsCache: (userId: string) => Promise<void>;
+/**
+ * Fire-and-forget variant of {@link invalidateEntitlementsCache} for call
+ * sites that must not await (or fail) the surrounding response on cache
+ * maintenance.
+ *
+ * @param userId - The user whose cached plan key must be dropped.
+ */
+export declare const invalidateEntitlementsCacheSafe: (userId: string) => void;
+//# sourceMappingURL=invalidateEntitlements.d.ts.map

package/dist/utilities/invalidateEntitlements.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"invalidateEntitlements.d.ts","sourceRoot":"","sources":["../../src/utilities/invalidateEntitlements.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,2BAA2B,GAAU,QAAQ,MAAM,KAAG,OAAO,CAAC,IAAI,CAQ9E,CAAA;AAED;;;;;;GAMG;AACH,eAAO,MAAM,+BAA+B,GAAI,QAAQ,MAAM,KAAG,IAMhE,CAAA"}

package/dist/utilities/invalidateEntitlements.js

@@ -0,0 +1,41 @@
+import { getLogger } from '@molecule/api-bond';
+const logger = getLogger();
+/**
+ * Invalidates the entitlements plan-key cache for a user after their plan
+ * changed (paid upgrade via `verifyPayment`, webhook grant/cancellation via
+ * `handlePaymentNotification`, admin `updatePlan`).
+ *
+ * `@molecule/api-entitlements` caches each user's effective plan key for its
+ * TTL (default 5 minutes) on the `getEffectiveTier` hot path. Without this
+ * call, a user who just PAID keeps seeing their old (free) tier — and a
+ * canceled user keeps premium — until the TTL lapses. The dependency is an
+ * OPTIONAL peer: apps that don't use entitlements simply have nothing to
+ * invalidate, so the import failure is a documented no-op.
+ *
+ * @param userId - The user whose cached plan key must be dropped.
+ */
+export const invalidateEntitlementsCache = async (userId) => {
+    try {
+        const entitlements = await import('@molecule/api-entitlements');
+        entitlements.invalidateCachedPlanKey?.(userId);
+    }
+    catch (_error) {
+        // @molecule/api-entitlements is an optional peer — when the app doesn't
+        // use entitlements there is no plan cache to invalidate.
+    }
+};
+/**
+ * Fire-and-forget variant of {@link invalidateEntitlementsCache} for call
+ * sites that must not await (or fail) the surrounding response on cache
+ * maintenance.
+ *
+ * @param userId - The user whose cached plan key must be dropped.
+ */
+export const invalidateEntitlementsCacheSafe = (userId) => {
+    invalidateEntitlementsCache(userId).catch((error) => {
+        // Never let cache maintenance break a payment path — but a failure here
+        // means the user sees a stale tier until the TTL lapses, so leave a trace.
+        logger.warn('entitlements cache invalidation failed', { userId, error });
+    });
+};
+//# sourceMappingURL=invalidateEntitlements.js.map

package/dist/utilities/invalidateEntitlements.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"invalidateEntitlements.js","sourceRoot":"","sources":["../../src/utilities/invalidateEntitlements.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAA;AAE9C,MAAM,MAAM,GAAG,SAAS,EAAE,CAAA;AAE1B;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,MAAM,2BAA2B,GAAG,KAAK,EAAE,MAAc,EAAiB,EAAE;IACjF,IAAI,CAAC;QACH,MAAM,YAAY,GAAG,MAAM,MAAM,CAAC,4BAA4B,CAAC,CAAA;QAC/D,YAAY,CAAC,uBAAuB,EAAE,CAAC,MAAM,CAAC,CAAA;IAChD,CAAC;IAAC,OAAO,MAAM,EAAE,CAAC;QAChB,wEAAwE;QACxE,yDAAyD;IAC3D,CAAC;AACH,CAAC,CAAA;AAED;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,+BAA+B,GAAG,CAAC,MAAc,EAAQ,EAAE;IACtE,2BAA2B,CAAC,MAAM,CAAC,CAAC,KAAK,CAAC,CAAC,KAAc,EAAE,EAAE;QAC3D,wEAAwE;QACxE,2EAA2E;QAC3E,MAAM,CAAC,IAAI,CAAC,wCAAwC,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,CAAA;IAC1E,CAAC,CAAC,CAAA;AACJ,CAAC,CAAA"}

package/dist/utilities/normalizeEmail.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Email normalization for the user resource.
+ *
+ * @module
+ */
+/**
+ * Normalizes an email address for storage and lookup so case/whitespace
+ * variants of the same mailbox cannot bypass the `email` UNIQUE constraint
+ * (e.g. `Foo@Example.com` vs `foo@example.com`).
+ *
+ * Trims surrounding whitespace and lowercases the whole address. While the
+ * local-part is technically case-sensitive per RFC 5321, every mainstream
+ * provider treats it case-insensitively, and the account-takeover risk of
+ * allowing variants far outweighs that pedantry. Both the local signup
+ * (`create`) and OAuth (`logInOAuth`) write paths MUST use this so the stored
+ * column and every collision lookup compare apples to apples.
+ *
+ * @param email - The raw email address (or null/undefined).
+ * @returns The normalized email, or `undefined` when the input is empty/blank.
+ */
+export declare const normalizeEmail: (email: string | null | undefined) => string | undefined;
+//# sourceMappingURL=normalizeEmail.d.ts.map

package/dist/utilities/normalizeEmail.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"normalizeEmail.d.ts","sourceRoot":"","sources":["../../src/utilities/normalizeEmail.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,cAAc,GAAI,OAAO,MAAM,GAAG,IAAI,GAAG,SAAS,KAAG,MAAM,GAAG,SAQ1E,CAAA"}

package/dist/utilities/normalizeEmail.js

@@ -0,0 +1,28 @@
+/**
+ * Email normalization for the user resource.
+ *
+ * @module
+ */
+/**
+ * Normalizes an email address for storage and lookup so case/whitespace
+ * variants of the same mailbox cannot bypass the `email` UNIQUE constraint
+ * (e.g. `Foo@Example.com` vs `foo@example.com`).
+ *
+ * Trims surrounding whitespace and lowercases the whole address. While the
+ * local-part is technically case-sensitive per RFC 5321, every mainstream
+ * provider treats it case-insensitively, and the account-takeover risk of
+ * allowing variants far outweighs that pedantry. Both the local signup
+ * (`create`) and OAuth (`logInOAuth`) write paths MUST use this so the stored
+ * column and every collision lookup compare apples to apples.
+ *
+ * @param email - The raw email address (or null/undefined).
+ * @returns The normalized email, or `undefined` when the input is empty/blank.
+ */
+export const normalizeEmail = (email) => {
+    if (typeof email !== 'string') {
+        return undefined;
+    }
+    const normalized = email.trim().toLowerCase();
+    return normalized.length > 0 ? normalized : undefined;
+};
+//# sourceMappingURL=normalizeEmail.js.map

package/dist/utilities/normalizeEmail.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"normalizeEmail.js","sourceRoot":"","sources":["../../src/utilities/normalizeEmail.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,KAAgC,EAAsB,EAAE;IACrF,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC9B,OAAO,SAAS,CAAA;IAClB,CAAC;IAED,MAAM,UAAU,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAA;IAE7C,OAAO,UAAU,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,SAAS,CAAA;AACvD,CAAC,CAAA"}

package/dist/utilities/notify.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Sends push notifications to all of a user's devices except the current one. Retrieves devices
+ * with active push subscriptions via the bonded DeviceService, then sends each notification via
+ * `@molecule/api-push-notifications`. Silently no-ops if either dependency is unavailable.
+ * @param options - Notification options.
+ * @param options.userId - The user whose devices should receive the notification.
+ * @param options.deviceId - The current device ID to exclude from notifications.
+ * @param options.title - The notification title text.
+ * @param options.titleKey - The i18n key for the title (sent as notification data for client-side localization).
+ * @param options.body - The notification body text.
+ * @param options.bodyKey - The i18n key for the body (sent as notification data for client-side localization).
+ */
+export declare const notify: ({ userId, deviceId, title, titleKey, body, bodyKey, }: {
+    userId: string;
+    deviceId?: string;
+    title: string;
+    titleKey?: string;
+    body: string;
+    bodyKey?: string;
+}) => Promise<void>;
+//# sourceMappingURL=notify.d.ts.map

package/dist/utilities/notify.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"notify.d.ts","sourceRoot":"","sources":["../../src/utilities/notify.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,MAAM,GAAU,uDAO1B;IACD,MAAM,EAAE,MAAM,CAAA;IACd,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,KAAK,EAAE,MAAM,CAAA;IACb,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,IAAI,EAAE,MAAM,CAAA;IACZ,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB,KAAG,OAAO,CAAC,IAAI,CA6Bf,CAAA"}

package/dist/utilities/notify.js

@@ -0,0 +1,39 @@
+import { get, getLogger } from '@molecule/api-bond';
+const logger = getLogger();
+/**
+ * Sends push notifications to all of a user's devices except the current one. Retrieves devices
+ * with active push subscriptions via the bonded DeviceService, then sends each notification via
+ * `@molecule/api-push-notifications`. Silently no-ops if either dependency is unavailable.
+ * @param options - Notification options.
+ * @param options.userId - The user whose devices should receive the notification.
+ * @param options.deviceId - The current device ID to exclude from notifications.
+ * @param options.title - The notification title text.
+ * @param options.titleKey - The i18n key for the title (sent as notification data for client-side localization).
+ * @param options.body - The notification body text.
+ * @param options.bodyKey - The i18n key for the body (sent as notification data for client-side localization).
+ */
+export const notify = async ({ userId, deviceId, title, titleKey, body, bodyKey, }) => {
+    try {
+        const pushNotifications = await import('@molecule/api-push-notifications').catch(() => null);
+        if (!pushNotifications)
+            return;
+        const deviceService = get('device');
+        if (!deviceService)
+            return;
+        const devices = await deviceService.getWithPushSubscription(userId);
+        for (const device of devices) {
+            if (device.id === deviceId)
+                continue;
+            try {
+                await pushNotifications.send(device.pushSubscription, { title, options: { body, data: { titleKey, bodyKey } } });
+            }
+            catch (error) {
+                logger.error(`Failed to send push to device ${device.id}:`, error);
+            }
+        }
+    }
+    catch (error) {
+        logger.error('notify error:', error);
+    }
+};
+//# sourceMappingURL=notify.js.map