@granular-software/sdk 0.4.10 → 0.4.11

package/README.md

@@ -48,6 +48,8 @@ CLI overrides:
 - `granular --prod <command>`
 - `granular --env local|production <command>`
 
+When the resolved API URL points at `localhost` or `127.0.0.1`, the SDK and CLI automatically swap opaque `sk_...` WorkOS keys for the local dev key `gn_sk_tenant_default_principal_local_e2e_00000000` so local runs work without server-side WorkOS validation. Override with `GRANULAR_LOCAL_API_KEY=...` or disable with `GRANULAR_DISABLE_LOCAL_API_KEY_FALLBACK=true`.
+
 ## Agent documentation (CLI)
 
 Projects created with `granular init` can include Markdown for coding agents (optional `AGENTS.md` plus generated guides):

package/dist/cli/index.js

@@ -5388,6 +5388,7 @@ var import_dotenv = __toESM(require_main());
 // src/endpoints.ts
 var LOCAL_API_URL = "ws://localhost:8787/granular";
 var PRODUCTION_API_URL = "wss://cf-api-gateway.arthur6084.workers.dev/granular";
+var DEFAULT_LOCAL_API_KEY = "gn_sk_tenant_default_principal_local_e2e_00000000";
 var LOCAL_AUTH_URL = "http://localhost:3000";
 var PRODUCTION_AUTH_URL = "https://app.granular.software";
 function readEnv(name) {
@@ -5407,6 +5408,21 @@ function isTruthy(value) {
   const normalized = value.trim().toLowerCase();
   return normalized === "1" || normalized === "true" || normalized === "yes" || normalized === "on";
 }
+function isLocalApiUrl(url) {
+  try {
+    const parsed = new URL(url);
+    return parsed.hostname === "localhost" || parsed.hostname === "127.0.0.1";
+  } catch {
+    return false;
+  }
+}
+function resolveAuthTokenForApiUrl(authToken, apiUrl) {
+  if (!authToken.startsWith("sk_") || !isLocalApiUrl(apiUrl) || isTruthy(readEnv("GRANULAR_DISABLE_LOCAL_API_KEY_FALLBACK"))) {
+    return authToken;
+  }
+  const override = readEnv("GRANULAR_LOCAL_API_KEY")?.trim();
+  return override || DEFAULT_LOCAL_API_KEY;
+}
 function resolveEndpointMode(explicitMode) {
   const explicit = normalizeMode(explicitMode);
   if (explicit === "local" || explicit === "production") {
@@ -6762,7 +6778,7 @@ var ApiClient = class {
   apiKey;
   baseUrl;
   constructor(apiKey, apiUrl) {
-    this.apiKey = apiKey;
+    this.apiKey = resolveAuthTokenForApiUrl(apiKey, apiUrl);
     this.baseUrl = apiUrl.replace("wss://", "https://").replace("ws://", "http://").replace(/\/ws$/, "");
   }
   async request(path4, options = {}) {
@@ -9722,7 +9738,7 @@ async function initCommand(projectName, options) {
   dim("  The seed script shows how records enter the graph. The effects script shows how external systems plug in.");
   console.log();
 }
-var DEFAULT_LOCAL_API_KEY = "gn_sk_tenant_default_principal_local_e2e_00000000";
+var DEFAULT_LOCAL_API_KEY2 = "gn_sk_tenant_default_principal_local_e2e_00000000";
 function promptSecret(question) {
   const rl = readline__namespace.createInterface({ input: process.stdin, output: process.stdout });
   return new Promise((resolve) => {
@@ -9748,7 +9764,7 @@ function maskApiKey(apiKey) {
   if (apiKey.length < 10) return `${apiKey}...`;
   return `${apiKey.substring(0, 10)}...`;
 }
-function isLocalApiUrl(apiUrl) {
+function isLocalApiUrl2(apiUrl) {
   return apiUrl.startsWith("ws://localhost:") || apiUrl.startsWith("wss://localhost:") || apiUrl.startsWith("ws://127.0.0.1:") || apiUrl.startsWith("wss://127.0.0.1:") || apiUrl.startsWith("http://localhost:") || apiUrl.startsWith("https://localhost:") || apiUrl.startsWith("http://127.0.0.1:") || apiUrl.startsWith("https://127.0.0.1:");
 }
 async function loginCommand(options = {}) {
@@ -9762,8 +9778,8 @@ async function loginCommand(options = {}) {
   const apiUrl = loadApiUrl();
   let apiKey = options.apiKey?.trim();
   if (!apiKey) {
-    if (!options.manual && isLocalApiUrl(apiUrl)) {
-      apiKey = existing?.trim() || process.env.GRANULAR_LOCAL_API_KEY?.trim() || DEFAULT_LOCAL_API_KEY;
+    if (!options.manual && isLocalApiUrl2(apiUrl)) {
+      apiKey = existing?.trim() || process.env.GRANULAR_LOCAL_API_KEY?.trim() || DEFAULT_LOCAL_API_KEY2;
       info("Using local Granular API key for localhost development.");
     } else if (options.manual) {
       dim("Get your API key at https://app.granular.software/w/default/api-keys");
@@ -10324,13 +10340,19 @@ function openUrl(url) {
   const cmd = platform === "darwin" ? "open" : platform === "win32" ? "start" : "xdg-open";
   child_process.spawn(cmd, [url], { stdio: "ignore", shell: platform === "win32" });
 }
-async function simulateCommand(sandboxIdArg) {
+async function simulateCommand(sandboxIdArg, options) {
   const sandboxId = sandboxIdArg ?? resolveConfig().sandboxId;
   if (!sandboxId) {
     error("No sandbox ID. Run from a project with `granular init` or pass a sandbox ID: granular simulate <sandbox-id>");
     process.exit(1);
   }
-  const url = `${SIMULATOR_BASE}?sandboxId=${encodeURIComponent(sandboxId)}`;
+  const params = new URLSearchParams({
+    sandboxId
+  });
+  if (options?.subjectId) {
+    params.set("subject_id", options.subjectId);
+  }
+  const url = `${SIMULATOR_BASE}?${params.toString()}`;
   info(`Opening simulator: ${url}`);
   openUrl(url);
 }
@@ -10470,9 +10492,9 @@ program2.command("document").description("Generate GRANULAR_SANDBOX.md (agent re
     process.exit(1);
   }
 });
-program2.command("simulate [sandbox-id]").description("Open the Granular simulator in the browser for the current (or given) sandbox").action(async (sandboxId) => {
+program2.command("simulate [sandbox-id]").description("Open the Granular simulator in the browser for the current (or given) sandbox").option("--subject-id <subjectId>", "Open the simulator preloaded for a specific subject").action(async (sandboxId, options) => {
   try {
-    await simulateCommand(sandboxId);
+    await simulateCommand(sandboxId, options);
   } catch (err) {
     error(err.message);
     process.exit(1);

package/dist/index.js

@@ -5316,6 +5316,7 @@ var JobImplementation = class {
 // src/endpoints.ts
 var LOCAL_API_URL = "ws://localhost:8787/granular";
 var PRODUCTION_API_URL = "wss://cf-api-gateway.arthur6084.workers.dev/granular";
+var DEFAULT_LOCAL_API_KEY = "gn_sk_tenant_default_principal_local_e2e_00000000";
 function readEnv(name) {
   if (typeof process === "undefined" || !process.env) return void 0;
   return process.env[name];
@@ -5333,6 +5334,21 @@ function isTruthy(value) {
   const normalized = value.trim().toLowerCase();
   return normalized === "1" || normalized === "true" || normalized === "yes" || normalized === "on";
 }
+function isLocalApiUrl(url) {
+  try {
+    const parsed = new URL(url);
+    return parsed.hostname === "localhost" || parsed.hostname === "127.0.0.1";
+  } catch {
+    return false;
+  }
+}
+function resolveAuthTokenForApiUrl(authToken, apiUrl) {
+  if (!authToken.startsWith("sk_") || !isLocalApiUrl(apiUrl) || isTruthy(readEnv("GRANULAR_DISABLE_LOCAL_API_KEY_FALLBACK"))) {
+    return authToken;
+  }
+  const override = readEnv("GRANULAR_LOCAL_API_KEY")?.trim();
+  return override || DEFAULT_LOCAL_API_KEY;
+}
 function resolveEndpointMode(explicitMode) {
   const explicit = normalizeMode(explicitMode);
   if (explicit === "local" || explicit === "production") {
@@ -6251,8 +6267,8 @@ var Granular = class {
     if (!auth) {
       throw new Error("Granular client requires either apiKey or token. Set GRANULAR_API_KEY or GRANULAR_TOKEN, or pass one in options.");
     }
-    this.apiKey = auth;
     this.apiUrl = resolveApiUrl(options.apiUrl, options.endpointMode);
+    this.apiKey = resolveAuthTokenForApiUrl(auth, this.apiUrl);
     this.tokenProvider = options.tokenProvider;
     this.WebSocketCtor = options.WebSocketCtor;
     this.onUnexpectedClose = options.onUnexpectedClose;