@hexclave/shared 1.0.23 → 1.0.24

package/src/ai/unified-prompts/skill-site-prompt-parts/ai-setup-prompt.ts

@@ -1,6 +1,7 @@
 import { ALL_APPS, type AppId } from "../../../apps/apps-config";
 import { typedEntries } from "../../../utils/objects";
 import { deindent } from "../../../utils/strings";
+import { remindersPrompt } from "../reminders";
 
 export const convexSetupPrompt = deindent`
   ## Convex Setup
@@ -593,6 +594,8 @@ const appSetupPrompt: Record<PublicAppSetupPromptId, string> =
     Then wire the SDK setup above: create the Hexclave App object, wrap React apps in the provider, and add handler/auth pages where your framework needs them. OAuth client IDs/secrets and trusted domains are environment-specific, so leave placeholders or ask the user for those instead of inventing them. See [Auth providers](https://docs.hexclave.com/guides/apps/authentication/auth-providers) and [hexclave.config.ts: Auth](https://docs.hexclave.com/guides/going-further/hexclave-config#auth).
   `,
   "fraud-protection": deindent`
+    Key concepts: sign-up rules are ordered checks that decide whether a sign-up should be allowed, rejected, restricted, or logged; rule priority decides which matching rule wins when multiple rules apply.
+
     Start by writing the first sign-up rules in \`hexclave.config.ts\`. For a company-only product, default to reject and explicitly allow the company domain:
 
     \`\`\`ts title="hexclave.config.ts"
@@ -633,6 +636,8 @@ const appSetupPrompt: Record<PublicAppSetupPromptId, string> =
     In the app, use team IDs in deep links wherever possible, then add a team switcher for navigation convenience. If team-specific authorization matters, configure RBAC next and enforce checks on the server. See [Teams](https://docs.hexclave.com/guides/apps/teams/overview), [Team Selection](https://docs.hexclave.com/guides/apps/teams/team-selection), and [hexclave.config.ts: Teams and Users](https://docs.hexclave.com/guides/going-further/hexclave-config#teams-and-users).
   `,
   "rbac": deindent`
+    Key concepts: permissions are stable IDs your app checks before protected actions; scopes decide whether a permission applies globally or within a team; contained permissions let one permission include other permissions recursively.
+
     Start with the permission IDs the product will check in code. For a basic team app, define reader/writer permissions and an admin-style composed permission:
 
     \`\`\`ts title="hexclave.config.ts"
@@ -663,6 +668,8 @@ const appSetupPrompt: Record<PublicAppSetupPromptId, string> =
     Use \`scope: "project"\` only for global project-level actions. Client-side permission checks are UX only; always enforce the same permissions on the server. See [RBAC Permissions](https://docs.hexclave.com/guides/apps/rbac/overview) and [hexclave.config.ts: RBAC](https://docs.hexclave.com/guides/going-further/hexclave-config#rbac).
   `,
   "api-keys": deindent`
+    API keys allow you to programmatically create API keys for your own users. This is useful if you have an API yourself that you want to authenticate users against.
+
     Start by enabling only the owner types the product actually needs. For a platform with both personal and workspace APIs:
 
     \`\`\`ts title="hexclave.config.ts"
@@ -681,6 +688,8 @@ const appSetupPrompt: Record<PublicAppSetupPromptId, string> =
     Then expose built-in account/team settings UI or build focused create/list/revoke screens. Always validate API keys on a trusted backend before serving protected requests. See [API Keys](https://docs.hexclave.com/guides/apps/api-keys/overview) and [hexclave.config.ts: API Keys](https://docs.hexclave.com/guides/going-further/hexclave-config#api-keys).
   `,
   "payments": deindent`
+    Key concepts: products are the sellable plans or one-time offers customers buy; product lines group mutually exclusive products such as pricing tiers; items are quantifiable entitlements such as credits, seats, or API calls granted by products; customers are the users, teams, or custom entities that own purchases and item balances.
+
     Start with a minimal catalog. For a user-plan SaaS with monthly credits:
 
     \`\`\`ts title="hexclave.config.ts"
@@ -691,6 +700,7 @@ const appSetupPrompt: Record<PublicAppSetupPromptId, string> =
         },
         items: {
           credits: { displayName: "Credits", customerType: "user" },
+          access: { displayName: "Product Access", customerType: "user" },
         },
         products: {
           pro: {
@@ -702,6 +712,7 @@ const appSetupPrompt: Record<PublicAppSetupPromptId, string> =
             },
             includedItems: {
               credits: { quantity: 1000, repeat: [1, "month"], expires: "when-repeated" },
+              access: { quantity: 1, expires: "when-purchase-expires" },
             },
           },
         },
@@ -714,6 +725,8 @@ const appSetupPrompt: Record<PublicAppSetupPromptId, string> =
     Keep purchases in test mode while building; Stripe connection and \`payments.testMode\` are environment-specific, so configure them in the dashboard/environment rather than hard-coding secrets. In code, generate checkout URLs and read products/items to gate access. See [Payments: Getting started](https://docs.hexclave.com/guides/apps/payments/overview#getting-started), [Defining products](https://docs.hexclave.com/guides/apps/payments/overview#defining-products), and [Checking item balances](https://docs.hexclave.com/guides/apps/payments/overview#checking-item-balances).
   `,
   "emails": deindent`
+    Key concepts: templates define reusable email content with variables; themes provide shared branding around templates; transactional emails are required product emails, while marketing emails must respect opt-out expectations.
+
     Start with delivery: shared delivery is fine for development, but production should use Managed, Resend, or custom SMTP from **Emails -> Email Settings**. Delivery credentials and sender settings are environment-specific, so do not put secrets in \`hexclave.config.ts\`.
 
     Use config for versioned content. For example, add a product-specific template once you have the copy:
@@ -1272,6 +1285,8 @@ export const aiSetupPrompt = deindent`
 
   To use it, you can use the sections below to set up Hexclave in the project. For example, if you are setting up a Svelte project, you would follow the SDK setup instructions for a frontend JS project.
 
+  ${remindersPrompt}
+
   ${getSdkSetupPrompt("ai-prompt")}
 
   ${convexSetupPrompt}

package/src/ai/unified-prompts/skill-site-prompt-parts/docs-json.generated.ts

@@ -255,68 +255,7 @@ const docsJson = {
       "/code-language-labels.js"
     ]
   },
-  "redirects": [
-    {
-      "source": "/sdk/objects/stack-app",
-      "destination": "/sdk/objects/hexclave-app"
-    },
-    {
-      "source": "/sdk/hooks/use-stack-app",
-      "destination": "/sdk/hooks/use-hexclave-app"
-    },
-    {
-      "source": "/rest-api/overview",
-      "destination": "/api/overview"
-    },
-    {
-      "source": "/getting-started/setup",
-      "destination": "/guides/getting-started/setup"
-    },
-    {
-      "source": "/docs/getting-started/setup",
-      "destination": "/guides/getting-started/setup"
-    },
-    {
-      "source": "/docs/next/getting-started/setup",
-      "destination": "/guides/getting-started/setup"
-    },
-    {
-      "source": "/docs/sdk",
-      "destination": "/sdk/overview"
-    },
-    {
-      "source": "/docs/apps/analytics",
-      "destination": "/guides/apps/analytics/overview"
-    },
-    {
-      "source": "/docs/apps/api-keys",
-      "destination": "/guides/apps/api-keys/overview"
-    },
-    {
-      "source": "/docs/others/convex",
-      "destination": "/guides/integrations/convex/overview"
-    },
-    {
-      "source": "/docs/concepts/teams",
-      "destination": "/guides/apps/teams/overview"
-    },
-    {
-      "source": "/docs/concepts/custom-user-data",
-      "destination": "/guides/getting-started/user-fundamentals#custom-metadata"
-    },
-    {
-      "source": "/guides/going-further/user-metadata",
-      "destination": "/guides/getting-started/user-fundamentals#custom-metadata"
-    },
-    {
-      "source": "/others/js-client",
-      "destination": "/sdk/objects/hexclave-app"
-    },
-    {
-      "source": "/guides/going-further/stack-app",
-      "destination": "/sdk/objects/hexclave-app"
-    }
-  ]
+  "redirects": []
 } as const;
 
 export default docsJson;

package/src/utils/env.test.tsx

@@ -0,0 +1,58 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { getEnvVariable, getProcessEnv, resolveHexclaveStackEnvVarValue } from "./env";
+
+afterEach(() => {
+  vi.unstubAllEnvs();
+});
+
+describe("Hexclave/Stack env var dual-read", () => {
+  it("falls back to the legacy Stack name when the Hexclave value is empty", () => {
+    vi.stubEnv("NEXT_PUBLIC_HEXCLAVE_API_URL", "");
+    vi.stubEnv("NEXT_PUBLIC_STACK_API_URL", "https://stack.example.test");
+
+    expect(getEnvVariable("NEXT_PUBLIC_STACK_API_URL")).toBe("https://stack.example.test");
+    expect(getProcessEnv("NEXT_PUBLIC_STACK_API_URL")).toBe("https://stack.example.test");
+  });
+
+  it("allows both names when they have the same non-empty value", () => {
+    vi.stubEnv("NEXT_PUBLIC_HEXCLAVE_API_URL", "https://api.example.test");
+    vi.stubEnv("NEXT_PUBLIC_STACK_API_URL", "https://api.example.test");
+
+    expect(getEnvVariable("NEXT_PUBLIC_STACK_API_URL")).toBe("https://api.example.test");
+    expect(getProcessEnv("NEXT_PUBLIC_STACK_API_URL")).toBe("https://api.example.test");
+  });
+
+  it("throws when both names are non-empty and different", () => {
+    vi.stubEnv("NEXT_PUBLIC_HEXCLAVE_API_URL", "https://hexclave.example.test");
+    vi.stubEnv("NEXT_PUBLIC_STACK_API_URL", "https://stack.example.test");
+
+    expect(() => getEnvVariable("NEXT_PUBLIC_STACK_API_URL")).toThrow(/NEXT_PUBLIC_HEXCLAVE_API_URL.*NEXT_PUBLIC_STACK_API_URL.*different values/);
+    expect(() => getProcessEnv("NEXT_PUBLIC_STACK_API_URL")).toThrow(/NEXT_PUBLIC_HEXCLAVE_API_URL.*NEXT_PUBLIC_STACK_API_URL.*different values/);
+  });
+
+  it("checks renamed legacy aliases when falling back", () => {
+    vi.stubEnv("NEXT_PUBLIC_HEXCLAVE_URL", "https://hexclave-url.example.test");
+    vi.stubEnv("NEXT_PUBLIC_STACK_URL", "https://stack-url.example.test");
+
+    expect(() => getEnvVariable("NEXT_PUBLIC_STACK_API_URL")).toThrow(/NEXT_PUBLIC_HEXCLAVE_URL.*NEXT_PUBLIC_STACK_URL.*different values/);
+  });
+
+  it("returns undefined when both names are empty", () => {
+    expect(resolveHexclaveStackEnvVarValue("HEXCLAVE_FOO", "STACK_FOO", "", "")).toBeUndefined();
+  });
+
+  it("falls back to the legacy Stack name when a canonical Hexclave name is looked up", () => {
+    vi.stubEnv("NEXT_PUBLIC_STACK_API_URL", "https://stack.example.test");
+
+    // Caller passes the canonical HEXCLAVE_ name but only the legacy value is set.
+    expect(getEnvVariable("NEXT_PUBLIC_HEXCLAVE_API_URL")).toBe("https://stack.example.test");
+    expect(getProcessEnv("NEXT_PUBLIC_HEXCLAVE_API_URL")).toBe("https://stack.example.test");
+  });
+
+  it("throws on a conflict when a canonical Hexclave name is looked up", () => {
+    vi.stubEnv("NEXT_PUBLIC_HEXCLAVE_API_URL", "https://hexclave.example.test");
+    vi.stubEnv("NEXT_PUBLIC_STACK_API_URL", "https://stack.example.test");
+
+    expect(() => getEnvVariable("NEXT_PUBLIC_HEXCLAVE_API_URL")).toThrow(/NEXT_PUBLIC_HEXCLAVE_API_URL.*NEXT_PUBLIC_STACK_API_URL.*different values/);
+  });
+});

package/src/utils/env.tsx

@@ -6,22 +6,37 @@ export function isBrowserLike() {
 }
 
 // newName: oldName
-const ENV_VAR_RENAME: Record<string, string[]> = {
+const ENV_VAR_RENAME: Record<string, string[] | undefined> = {
   NEXT_PUBLIC_STACK_API_URL: ['STACK_BASE_URL', 'NEXT_PUBLIC_STACK_URL'],
 };
 
+export function resolveHexclaveStackEnvVarValue(hexclaveName: string, stackName: string, hexclaveValue: string | undefined, stackValue: string | undefined): string | undefined {
+  if (hexclaveValue && stackValue && hexclaveValue !== stackValue) {
+    throw new Error(`Environment variables ${hexclaveName} and ${stackName} are both set to different values. Remove one of them or set them to the same value.`);
+  }
+  return hexclaveValue || stackValue || undefined;
+}
+
 /**
- * Hexclave rebrand: compute the `HEXCLAVE_*`-prefixed equivalent of a `STACK_*`
- * env var name by replacing the first `STACK_` occurrence with `HEXCLAVE_`.
- * Covers `STACK_FOO`, `NEXT_PUBLIC_STACK_FOO`, `NEXT_PUBLIC_BROWSER_STACK_FOO`,
- * `NEXT_PUBLIC_SERVER_STACK_FOO`, `VITE_STACK_FOO`. Returns `undefined` when the
- * name has no `STACK_` segment (caller should behave exactly as before).
+ * Hexclave rebrand: resolve an env var by reading both the `HEXCLAVE_*` and
+ * `STACK_*` spellings, preferring the canonical Hexclave value and falling back
+ * to the legacy Stack value (empty counts as unset). Works in BOTH directions —
+ * whether the caller passes the legacy `STACK_FOO` name or the canonical
+ * `HEXCLAVE_FOO` name, the other spelling is still honored. Covers `STACK_FOO`,
+ * `NEXT_PUBLIC_STACK_FOO`, `NEXT_PUBLIC_BROWSER_STACK_FOO`,
+ * `NEXT_PUBLIC_SERVER_STACK_FOO`, `VITE_STACK_FOO` and their HEXCLAVE_ twins.
+ * Names with neither segment behave exactly as before.
  */
-function getHexclaveEnvVarName(name: string): string | undefined {
-  if (!name.includes("STACK_")) {
-    return undefined;
+function getEnvVarWithHexclaveFallback(name: string): string | undefined {
+  if (name.includes("STACK_")) {
+    const hexclaveName = name.replace("STACK_", "HEXCLAVE_");
+    return resolveHexclaveStackEnvVarValue(hexclaveName, name, process.env[hexclaveName], process.env[name]);
+  }
+  if (name.includes("HEXCLAVE_")) {
+    const stackName = name.replace("HEXCLAVE_", "STACK_");
+    return resolveHexclaveStackEnvVarValue(name, stackName, process.env[name], process.env[stackName]);
   }
-  return name.replace("STACK_", "HEXCLAVE_");
+  return process.env[name];
 }
 
 /**
@@ -45,21 +60,21 @@ export function getEnvVariable(name: string, defaultValue?: string | undefined):
 
   // throw error if the old name is used as the retrieve key
   for (const [newName, oldNames] of Object.entries(ENV_VAR_RENAME)) {
-    if (oldNames.includes(name)) {
+    if (oldNames?.includes(name)) {
       throwErr(`Environment variable ${name} has been renamed to ${newName}. Please update your configuration to use the new name.`);
     }
   }
 
   // Hexclave rebrand: prefer the HEXCLAVE_*-prefixed equivalent, fall back to the STACK_* name.
-  const hexclaveName = getHexclaveEnvVarName(name);
-  let value = (hexclaveName ? process.env[hexclaveName] : undefined) ?? process.env[name];
+  // Treat the empty string as unset — the checked-in .env templates define empty
+  // HEXCLAVE_* placeholders, which must not shadow a real value under the legacy name.
+  let value = getEnvVarWithHexclaveFallback(name);
 
   // check the key under the old name if the new name is not found
-  if (!value && ENV_VAR_RENAME[name] as any) {
-    for (const oldName of ENV_VAR_RENAME[name]) {
-      // Hexclave rebrand: also accept the HEXCLAVE_*-prefixed equivalent of each old alias.
-      const hexclaveOldName = getHexclaveEnvVarName(oldName);
-      value = (hexclaveOldName ? process.env[hexclaveOldName] : undefined) ?? process.env[oldName];
+  const renamedNames = ENV_VAR_RENAME[name];
+  if (!value && renamedNames != null) {
+    for (const oldName of renamedNames) {
+      value = getEnvVarWithHexclaveFallback(oldName);
       if (value) break;
     }
   }
@@ -112,6 +127,7 @@ export function getProcessEnv(name: string): string | undefined {
     return undefined;
   }
   // Hexclave rebrand: prefer the HEXCLAVE_*-prefixed equivalent, fall back to the STACK_* name.
-  const hexclaveName = getHexclaveEnvVarName(name);
-  return (hexclaveName ? process.env[hexclaveName] : undefined) ?? process.env[name];
+  // Empty counts as unset — the checked-in .env templates define empty HEXCLAVE_* placeholders,
+  // which must not shadow a real value under the legacy name.
+  return getEnvVarWithHexclaveFallback(name);
 }

package/src/utils/errors.tsx

@@ -80,7 +80,12 @@ export class HexclaveAssertionError extends Error {
 
     // Use literal dot-form (guarded with `typeof process`) so Next.js / webpack
     // DefinePlugin can inline the value at build time. See getProcessEnv in ./env.
-    if ((typeof process !== "undefined" ? process.env.NEXT_PUBLIC_STACK_DEBUGGER_ON_ASSERTION_ERROR : undefined) === "true") {
+    const hexclaveDebuggerValue = typeof process !== "undefined" ? process.env.NEXT_PUBLIC_HEXCLAVE_DEBUGGER_ON_ASSERTION_ERROR : undefined;
+    const stackDebuggerValue = typeof process !== "undefined" ? process.env.NEXT_PUBLIC_STACK_DEBUGGER_ON_ASSERTION_ERROR : undefined;
+    if (hexclaveDebuggerValue && stackDebuggerValue && hexclaveDebuggerValue !== stackDebuggerValue) {
+      throw new Error("Environment variables NEXT_PUBLIC_HEXCLAVE_DEBUGGER_ON_ASSERTION_ERROR and NEXT_PUBLIC_STACK_DEBUGGER_ON_ASSERTION_ERROR are both set to different values. Remove one of them or set them to the same value.");
+    }
+    if ((hexclaveDebuggerValue || stackDebuggerValue) === "true") {
       debugger;
     }
   }