workos 0.15.2 → 0.16.0

package/dist/lib/api-error-handler.js

@@ -1,57 +1,75 @@
 import { WorkOSApiError } from './workos-api.js';
 import { exitWithError } from '../utils/output.js';
-/**
- * Duck-type check for @workos-inc/node SDK exceptions.
- *
- * The SDK throws typed errors (UnauthorizedException, NotFoundException, etc.)
- * that implement the RequestException interface: { status, message, requestID }.
- * We duck-type rather than instanceof to avoid coupling to the SDK's class hierarchy.
- */
-function isSdkException(error) {
+export function isSdkException(error) {
     if (!(error instanceof Error))
         return false;
     const e = error;
     return typeof e.status === 'number' && typeof e.requestID === 'string';
 }
+function normalizeApiError(error) {
+    if (error instanceof WorkOSApiError) {
+        return {
+            status: error.statusCode,
+            code: error.code,
+            errors: error.errors,
+            message: error.message,
+        };
+    }
+    if (isSdkException(error)) {
+        return {
+            status: error.status,
+            code: error.code,
+            errors: error.errors,
+            message: error.message,
+        };
+    }
+    return null;
+}
+function getApiErrorMessage(error, label) {
+    if (error.status === 401)
+        return 'Invalid API key. Check your environment configuration.';
+    if (error.status === 404)
+        return `${label} not found.`;
+    if (error.status === 422 && error.errors?.length)
+        return error.errors.map((e) => e.message).join(', ');
+    return error.message;
+}
 /**
  * Create a resource-specific API error handler.
- * Handles both raw fetch errors (WorkOSApiError) and SDK exceptions.
- * Returns a `never` function that writes structured errors and exits.
+ * Handles raw fetch errors (WorkOSApiError), SDK exceptions, and the SDK's
+ * "errors is not iterable" TypeError from malformed 422 responses.
+ *
+ * `context` optionally names the specific resource instance (e.g. a vault
+ * object name) so 404 messages can be more specific.
  */
 export function createApiErrorHandler(resourceName) {
-    return (error) => {
-        // 1. Raw fetch errors (workos-api.ts)
-        if (error instanceof WorkOSApiError) {
+    return (error, context) => {
+        if (error instanceof TypeError && error.message.includes('errors is not iterable')) {
             exitWithError({
-                code: error.code ?? `http_${error.statusCode}`,
-                message: error.statusCode === 401
-                    ? 'Invalid API key. Check your environment configuration.'
-                    : error.statusCode === 404
-                        ? `${resourceName} not found.`
-                        : error.statusCode === 422 && error.errors?.length
-                            ? error.errors.map((e) => e.message).join(', ')
-                            : error.message,
-                details: error.errors,
+                code: 'unprocessable_entity',
+                message: `${resourceName} API rejected the request. Check that all required fields are provided.`,
+                apiContext: { resource: resourceName },
             });
         }
-        // 2. SDK exceptions (@workos-inc/node)
-        if (isSdkException(error)) {
+        const label = context ? `${resourceName} '${context}'` : resourceName;
+        const apiError = normalizeApiError(error);
+        if (apiError) {
+            const code = apiError.code ?? `http_${apiError.status}`;
             exitWithError({
-                code: error.code ?? `http_${error.status}`,
-                message: error.status === 401
-                    ? 'Invalid API key. Check your environment configuration.'
-                    : error.status === 404
-                        ? `${resourceName} not found.`
-                        : error.status === 422 && error.errors?.length
-                            ? error.errors.map((e) => e.message).join(', ')
-                            : error.message,
-                details: error.errors,
+                code,
+                message: getApiErrorMessage(apiError, label),
+                details: apiError.errors,
+                apiContext: {
+                    status: apiError.status,
+                    code,
+                    resource: resourceName,
+                },
             });
         }
-        // 3. Fallback
         exitWithError({
             code: 'unknown_error',
             message: error instanceof Error ? error.message : 'Unknown error',
+            apiContext: { resource: resourceName },
         });
     };
 }

package/dist/lib/api-error-handler.js.map

@@ -1 +1 @@
-{"version":3,"file":"api-error-handler.js","sourceRoot":"","sources":["../../src/lib/api-error-handler.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AACjD,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAEnD;;;;;;GAMG;AACH,SAAS,cAAc,CACrB,KAAc;IAEd,IAAI,CAAC,CAAC,KAAK,YAAY,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC;IAC5C,MAAM,CAAC,GAAG,KAA0D,CAAC;IACrE,OAAO,OAAO,CAAC,CAAC,MAAM,KAAK,QAAQ,IAAI,OAAO,CAAC,CAAC,SAAS,KAAK,QAAQ,CAAC;AACzE,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,qBAAqB,CAAC,YAAoB;IACxD,OAAO,CAAC,KAAc,EAAS,EAAE;QAC/B,sCAAsC;QACtC,IAAI,KAAK,YAAY,cAAc,EAAE,CAAC;YACpC,aAAa,CAAC;gBACZ,IAAI,EAAE,KAAK,CAAC,IAAI,IAAI,QAAQ,KAAK,CAAC,UAAU,EAAE;gBAC9C,OAAO,EACL,KAAK,CAAC,UAAU,KAAK,GAAG;oBACtB,CAAC,CAAC,wDAAwD;oBAC1D,CAAC,CAAC,KAAK,CAAC,UAAU,KAAK,GAAG;wBACxB,CAAC,CAAC,GAAG,YAAY,aAAa;wBAC9B,CAAC,CAAC,KAAK,CAAC,UAAU,KAAK,GAAG,IAAI,KAAK,CAAC,MAAM,EAAE,MAAM;4BAChD,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC;4BAC/C,CAAC,CAAC,KAAK,CAAC,OAAO;gBACvB,OAAO,EAAE,KAAK,CAAC,MAAM;aACtB,CAAC,CAAC;QACL,CAAC;QAED,uCAAuC;QACvC,IAAI,cAAc,CAAC,KAAK,CAAC,EAAE,CAAC;YAC1B,aAAa,CAAC;gBACZ,IAAI,EAAE,KAAK,CAAC,IAAI,IAAI,QAAQ,KAAK,CAAC,MAAM,EAAE;gBAC1C,OAAO,EACL,KAAK,CAAC,MAAM,KAAK,GAAG;oBAClB,CAAC,CAAC,wDAAwD;oBAC1D,CAAC,CAAC,KAAK,CAAC,MAAM,KAAK,GAAG;wBACpB,CAAC,CAAC,GAAG,YAAY,aAAa;wBAC9B,CAAC,CAAC,KAAK,CAAC,MAAM,KAAK,GAAG,IAAI,KAAK,CAAC,MAAM,EAAE,MAAM;4BAC5C,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC;4BAC/C,CAAC,CAAC,KAAK,CAAC,OAAO;gBACvB,OAAO,EAAE,KAAK,CAAC,MAAM;aACtB,CAAC,CAAC;QACL,CAAC;QAED,cAAc;QACd,aAAa,CAAC;YACZ,IAAI,EAAE,eAAe;YACrB,OAAO,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,eAAe;SAClE,CAAC,CAAC;IACL,CAAC,CAAC;AACJ,CAAC","sourcesContent":["import { WorkOSApiError } from './workos-api.js';\nimport { exitWithError } from '../utils/output.js';\n\n/**\n * Duck-type check for @workos-inc/node SDK exceptions.\n *\n * The SDK throws typed errors (UnauthorizedException, NotFoundException, etc.)\n * that implement the RequestException interface: { status, message, requestID }.\n * We duck-type rather than instanceof to avoid coupling to the SDK's class hierarchy.\n */\nfunction isSdkException(\n  error: unknown,\n): error is { status: number; message: string; requestID: string; code?: string; errors?: Array<{ message: string }> } {\n  if (!(error instanceof Error)) return false;\n  const e = error as Error & { status?: unknown; requestID?: unknown };\n  return typeof e.status === 'number' && typeof e.requestID === 'string';\n}\n\n/**\n * Create a resource-specific API error handler.\n * Handles both raw fetch errors (WorkOSApiError) and SDK exceptions.\n * Returns a `never` function that writes structured errors and exits.\n */\nexport function createApiErrorHandler(resourceName: string) {\n  return (error: unknown): never => {\n    // 1. Raw fetch errors (workos-api.ts)\n    if (error instanceof WorkOSApiError) {\n      exitWithError({\n        code: error.code ?? `http_${error.statusCode}`,\n        message:\n          error.statusCode === 401\n            ? 'Invalid API key. Check your environment configuration.'\n            : error.statusCode === 404\n              ? `${resourceName} not found.`\n              : error.statusCode === 422 && error.errors?.length\n                ? error.errors.map((e) => e.message).join(', ')\n                : error.message,\n        details: error.errors,\n      });\n    }\n\n    // 2. SDK exceptions (@workos-inc/node)\n    if (isSdkException(error)) {\n      exitWithError({\n        code: error.code ?? `http_${error.status}`,\n        message:\n          error.status === 401\n            ? 'Invalid API key. Check your environment configuration.'\n            : error.status === 404\n              ? `${resourceName} not found.`\n              : error.status === 422 && error.errors?.length\n                ? error.errors.map((e) => e.message).join(', ')\n                : error.message,\n        details: error.errors,\n      });\n    }\n\n    // 3. Fallback\n    exitWithError({\n      code: 'unknown_error',\n      message: error instanceof Error ? error.message : 'Unknown error',\n    });\n  };\n}\n"]}
+{"version":3,"file":"api-error-handler.js","sourceRoot":"","sources":["../../src/lib/api-error-handler.ts"],"names":[],"mappings":"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","sourcesContent":["import { WorkOSApiError } from './workos-api.js';\nimport { exitWithError } from '../utils/output.js';\n\nexport function isSdkException(\n  error: unknown,\n): error is { status: number; message: string; requestID: string; code?: string; errors?: Array<{ message: string }> } {\n  if (!(error instanceof Error)) return false;\n  const e = error as Error & { status?: unknown; requestID?: unknown };\n  return typeof e.status === 'number' && typeof e.requestID === 'string';\n}\n\ninterface NormalizedApiError {\n  status: number;\n  code?: string;\n  errors?: Array<{ message: string }>;\n  message: string;\n}\n\nfunction normalizeApiError(error: unknown): NormalizedApiError | null {\n  if (error instanceof WorkOSApiError) {\n    return {\n      status: error.statusCode,\n      code: error.code,\n      errors: error.errors,\n      message: error.message,\n    };\n  }\n\n  if (isSdkException(error)) {\n    return {\n      status: error.status,\n      code: error.code,\n      errors: error.errors,\n      message: error.message,\n    };\n  }\n\n  return null;\n}\n\nfunction getApiErrorMessage(error: NormalizedApiError, label: string): string {\n  if (error.status === 401) return 'Invalid API key. Check your environment configuration.';\n  if (error.status === 404) return `${label} not found.`;\n  if (error.status === 422 && error.errors?.length) return error.errors.map((e) => e.message).join(', ');\n  return error.message;\n}\n\n/**\n * Create a resource-specific API error handler.\n * Handles raw fetch errors (WorkOSApiError), SDK exceptions, and the SDK's\n * \"errors is not iterable\" TypeError from malformed 422 responses.\n *\n * `context` optionally names the specific resource instance (e.g. a vault\n * object name) so 404 messages can be more specific.\n */\nexport function createApiErrorHandler(resourceName: string) {\n  return (error: unknown, context?: string): never => {\n    if (error instanceof TypeError && error.message.includes('errors is not iterable')) {\n      exitWithError({\n        code: 'unprocessable_entity',\n        message: `${resourceName} API rejected the request. Check that all required fields are provided.`,\n        apiContext: { resource: resourceName },\n      });\n    }\n\n    const label = context ? `${resourceName} '${context}'` : resourceName;\n    const apiError = normalizeApiError(error);\n    if (apiError) {\n      const code = apiError.code ?? `http_${apiError.status}`;\n      exitWithError({\n        code,\n        message: getApiErrorMessage(apiError, label),\n        details: apiError.errors,\n        apiContext: {\n          status: apiError.status,\n          code,\n          resource: resourceName,\n        },\n      });\n    }\n\n    exitWithError({\n      code: 'unknown_error',\n      message: error instanceof Error ? error.message : 'Unknown error',\n      apiContext: { resource: resourceName },\n    });\n  };\n}\n"]}

package/dist/lib/command-aliases.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Shared canonical command alias map.
+ * Single source of truth for both telemetry and help-json.
+ *
+ * Keys are user-facing aliases, values are canonical command names.
+ * Adding an alias here updates both metrics aggregation and --help --json output.
+ */
+export declare const COMMAND_ALIASES: Record<string, string>;

package/dist/lib/command-aliases.js

@@ -0,0 +1,12 @@
+/**
+ * Shared canonical command alias map.
+ * Single source of truth for both telemetry and help-json.
+ *
+ * Keys are user-facing aliases, values are canonical command names.
+ * Adding an alias here updates both metrics aggregation and --help --json output.
+ */
+export const COMMAND_ALIASES = {
+    org: 'organization',
+    claim: 'env.claim',
+};
+//# sourceMappingURL=command-aliases.js.map

package/dist/lib/command-aliases.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"command-aliases.js","sourceRoot":"","sources":["../../src/lib/command-aliases.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,eAAe,GAA2B;IACrD,GAAG,EAAE,cAAc;IACnB,KAAK,EAAE,WAAW;CACnB,CAAC","sourcesContent":["/**\n * Shared canonical command alias map.\n * Single source of truth for both telemetry and help-json.\n *\n * Keys are user-facing aliases, values are canonical command names.\n * Adding an alias here updates both metrics aggregation and --help --json output.\n */\nexport const COMMAND_ALIASES: Record<string, string> = {\n  org: 'organization',\n  claim: 'env.claim',\n};\n"]}

package/dist/lib/constants.d.ts

@@ -26,7 +26,6 @@ export declare const WORKOS_DASHBOARD_URL: string;
 export declare const ISSUES_URL: string;
 export declare const ANALYTICS_ENABLED: boolean;
 export declare const INSTALLER_INTERACTION_EVENT_NAME: string;
-export declare const WORKOS_TELEMETRY_ENABLED: boolean;
 export declare const OAUTH_PORT: number;
 /**
  * Common glob patterns to ignore when searching for files.

package/dist/lib/constants.js

@@ -18,7 +18,6 @@ export const WORKOS_DASHBOARD_URL = settings.documentation.dashboardUrl;
 export const ISSUES_URL = settings.documentation.issuesUrl;
 export const ANALYTICS_ENABLED = settings.telemetry.enabled;
 export const INSTALLER_INTERACTION_EVENT_NAME = settings.telemetry.eventName;
-export const WORKOS_TELEMETRY_ENABLED = process.env.WORKOS_TELEMETRY !== 'false';
 export const OAUTH_PORT = settings.legacy.oauthPort;
 /**
  * Common glob patterns to ignore when searching for files.

package/dist/lib/constants.js.map

@@ -1 +1 @@
-{"version":3,"file":"constants.js","sourceRoot":"","sources":["../../src/lib/constants.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAS1C;;;GAGG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG;IAChC,MAAM,EAAE,QAAQ;IAChB,KAAK,EAAE,OAAO;IACd,aAAa,EAAE,gBAAgB;IAC/B,WAAW,EAAE,cAAc;IAC3B,SAAS,EAAE,YAAY;CACf,CAAC;AAOX,MAAM,CAAC,MAAM,MAAM,GAAG,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,QAAQ,IAAI,EAAE,CAAC,CAAC;AAEnF,MAAM,QAAQ,GAAG,SAAS,EAAE,CAAC;AAE7B,MAAM,CAAC,MAAM,KAAK,GAAG,QAAQ,CAAC,OAAO,CAAC,SAAS,CAAC;AAChD,MAAM,CAAC,MAAM,eAAe,GAAG,QAAQ,CAAC,aAAa,CAAC,aAAa,CAAC;AACpE,MAAM,CAAC,MAAM,oBAAoB,GAAG,QAAQ,CAAC,aAAa,CAAC,YAAY,CAAC;AACxE,MAAM,CAAC,MAAM,UAAU,GAAG,QAAQ,CAAC,aAAa,CAAC,SAAS,CAAC;AAC3D,MAAM,CAAC,MAAM,iBAAiB,GAAG,QAAQ,CAAC,SAAS,CAAC,OAAO,CAAC;AAC5D,MAAM,CAAC,MAAM,gCAAgC,GAAG,QAAQ,CAAC,SAAS,CAAC,SAAS,CAAC;AAC7E,MAAM,CAAC,MAAM,wBAAwB,GAAG,OAAO,CAAC,GAAG,CAAC,gBAAgB,KAAK,OAAO,CAAC;AACjF,MAAM,CAAC,MAAM,UAAU,GAAG,QAAQ,CAAC,MAAM,CAAC,SAAS,CAAC;AAEpD;;;GAGG;AACH,MAAM,CAAC,MAAM,eAAe,GAAa;IACvC,oBAAoB;IACpB,YAAY;IACZ,aAAa;IACb,cAAc;IACd,aAAa;CACd,CAAC","sourcesContent":["import { getConfig } from './settings.js';\n\n/**\n * Integration identifier type.\n * No longer an enum — each integration self-registers via the auto-discovery registry.\n * The string value matches the integration directory name (e.g., 'nextjs', 'react-router').\n */\nexport type Integration = string;\n\n/**\n * Well-known integration names for backwards compatibility.\n * New integrations do NOT need to be added here — they're auto-discovered.\n */\nexport const KNOWN_INTEGRATIONS = {\n  nextjs: 'nextjs',\n  react: 'react',\n  tanstackStart: 'tanstack-start',\n  reactRouter: 'react-router',\n  vanillaJs: 'vanilla-js',\n} as const;\n\nexport interface Args {\n  debug: boolean;\n  integration: Integration;\n}\n\nexport const IS_DEV = ['test', 'development'].includes(process.env.NODE_ENV ?? '');\n\nconst settings = getConfig();\n\nexport const DEBUG = settings.logging.debugMode;\nexport const WORKOS_DOCS_URL = settings.documentation.workosDocsUrl;\nexport const WORKOS_DASHBOARD_URL = settings.documentation.dashboardUrl;\nexport const ISSUES_URL = settings.documentation.issuesUrl;\nexport const ANALYTICS_ENABLED = settings.telemetry.enabled;\nexport const INSTALLER_INTERACTION_EVENT_NAME = settings.telemetry.eventName;\nexport const WORKOS_TELEMETRY_ENABLED = process.env.WORKOS_TELEMETRY !== 'false';\nexport const OAUTH_PORT = settings.legacy.oauthPort;\n\n/**\n * Common glob patterns to ignore when searching for files.\n * Used by multiple integrations.\n */\nexport const IGNORE_PATTERNS: string[] = [\n  '**/node_modules/**',\n  '**/dist/**',\n  '**/build/**',\n  '**/public/**',\n  '**/.next/**',\n];\n"]}
+{"version":3,"file":"constants.js","sourceRoot":"","sources":["../../src/lib/constants.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAS1C;;;GAGG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG;IAChC,MAAM,EAAE,QAAQ;IAChB,KAAK,EAAE,OAAO;IACd,aAAa,EAAE,gBAAgB;IAC/B,WAAW,EAAE,cAAc;IAC3B,SAAS,EAAE,YAAY;CACf,CAAC;AAOX,MAAM,CAAC,MAAM,MAAM,GAAG,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,QAAQ,IAAI,EAAE,CAAC,CAAC;AAEnF,MAAM,QAAQ,GAAG,SAAS,EAAE,CAAC;AAE7B,MAAM,CAAC,MAAM,KAAK,GAAG,QAAQ,CAAC,OAAO,CAAC,SAAS,CAAC;AAChD,MAAM,CAAC,MAAM,eAAe,GAAG,QAAQ,CAAC,aAAa,CAAC,aAAa,CAAC;AACpE,MAAM,CAAC,MAAM,oBAAoB,GAAG,QAAQ,CAAC,aAAa,CAAC,YAAY,CAAC;AACxE,MAAM,CAAC,MAAM,UAAU,GAAG,QAAQ,CAAC,aAAa,CAAC,SAAS,CAAC;AAC3D,MAAM,CAAC,MAAM,iBAAiB,GAAG,QAAQ,CAAC,SAAS,CAAC,OAAO,CAAC;AAC5D,MAAM,CAAC,MAAM,gCAAgC,GAAG,QAAQ,CAAC,SAAS,CAAC,SAAS,CAAC;AAC7E,MAAM,CAAC,MAAM,UAAU,GAAG,QAAQ,CAAC,MAAM,CAAC,SAAS,CAAC;AAEpD;;;GAGG;AACH,MAAM,CAAC,MAAM,eAAe,GAAa;IACvC,oBAAoB;IACpB,YAAY;IACZ,aAAa;IACb,cAAc;IACd,aAAa;CACd,CAAC","sourcesContent":["import { getConfig } from './settings.js';\n\n/**\n * Integration identifier type.\n * No longer an enum — each integration self-registers via the auto-discovery registry.\n * The string value matches the integration directory name (e.g., 'nextjs', 'react-router').\n */\nexport type Integration = string;\n\n/**\n * Well-known integration names for backwards compatibility.\n * New integrations do NOT need to be added here — they're auto-discovered.\n */\nexport const KNOWN_INTEGRATIONS = {\n  nextjs: 'nextjs',\n  react: 'react',\n  tanstackStart: 'tanstack-start',\n  reactRouter: 'react-router',\n  vanillaJs: 'vanilla-js',\n} as const;\n\nexport interface Args {\n  debug: boolean;\n  integration: Integration;\n}\n\nexport const IS_DEV = ['test', 'development'].includes(process.env.NODE_ENV ?? '');\n\nconst settings = getConfig();\n\nexport const DEBUG = settings.logging.debugMode;\nexport const WORKOS_DOCS_URL = settings.documentation.workosDocsUrl;\nexport const WORKOS_DASHBOARD_URL = settings.documentation.dashboardUrl;\nexport const ISSUES_URL = settings.documentation.issuesUrl;\nexport const ANALYTICS_ENABLED = settings.telemetry.enabled;\nexport const INSTALLER_INTERACTION_EVENT_NAME = settings.telemetry.eventName;\nexport const OAUTH_PORT = settings.legacy.oauthPort;\n\n/**\n * Common glob patterns to ignore when searching for files.\n * Used by multiple integrations.\n */\nexport const IGNORE_PATTERNS: string[] = [\n  '**/node_modules/**',\n  '**/dist/**',\n  '**/build/**',\n  '**/public/**',\n  '**/.next/**',\n];\n"]}

package/dist/lib/device-id.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Persistent device identifier for telemetry correlation.
+ *
+ * Stored at ~/.workos/device-id as a plain UTF-8 UUID string. Not a secret
+ * — this is a convenience identifier that survives keyring unavailability.
+ * Any IO failure falls through to a one-shot UUID for the current session.
+ */
+/**
+ * Asynchronously resolve (and lazily create) the device id without blocking
+ * the event loop. Memoized: the first call performs the IO, concurrent and
+ * later callers await the same promise. Populates the shared cache that the
+ * synchronous getDeviceId() reads, so prewarming this at startup keeps the
+ * synchronous telemetry path off blocking fs IO. Never rejects.
+ */
+export declare function loadDeviceId(): Promise<string>;
+/**
+ * Synchronous accessor for the telemetry event path. Returns the prewarmed
+ * value when loadDeviceId() has run; otherwise falls back to a one-time
+ * synchronous read of the same file (returning the persisted id, so the value
+ * never diverges from the async path). On any IO failure, returns a one-shot
+ * UUID scoped to the current process — never throws.
+ */
+export declare function getDeviceId(): string;
+/** Test seam — resets the in-memory cache between test cases. */
+export declare function __resetDeviceIdCache(): void;

package/dist/lib/device-id.js

@@ -0,0 +1,102 @@
+/**
+ * Persistent device identifier for telemetry correlation.
+ *
+ * Stored at ~/.workos/device-id as a plain UTF-8 UUID string. Not a secret
+ * — this is a convenience identifier that survives keyring unavailability.
+ * Any IO failure falls through to a one-shot UUID for the current session.
+ */
+import fs from 'node:fs';
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import os from 'node:os';
+import crypto from 'node:crypto';
+// RFC 4122 v4 format — matches what `crypto.randomUUID()` produces.
+// Rejects non-UUID strings like "------------------------------------".
+const UUID_V4_REGEX = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+let cached;
+let pending;
+function getDeviceIdPath() {
+    return path.join(os.homedir(), '.workos', 'device-id');
+}
+/**
+ * Asynchronously resolve (and lazily create) the device id without blocking
+ * the event loop. Memoized: the first call performs the IO, concurrent and
+ * later callers await the same promise. Populates the shared cache that the
+ * synchronous getDeviceId() reads, so prewarming this at startup keeps the
+ * synchronous telemetry path off blocking fs IO. Never rejects.
+ */
+export function loadDeviceId() {
+    if (cached)
+        return Promise.resolve(cached);
+    if (pending)
+        return pending;
+    pending = (async () => {
+        const filePath = getDeviceIdPath();
+        try {
+            try {
+                const raw = (await readFile(filePath, 'utf8')).trim();
+                if (UUID_V4_REGEX.test(raw)) {
+                    cached = raw;
+                    return raw;
+                }
+            }
+            catch {
+                // Missing/unreadable file — fall through and create it.
+            }
+            const id = crypto.randomUUID();
+            await mkdir(path.dirname(filePath), { recursive: true, mode: 0o700 });
+            await writeFile(filePath, id, { encoding: 'utf8', mode: 0o600 });
+            cached = id;
+            return id;
+        }
+        catch {
+            // IO failure (readonly FS, permission denied, etc.) — fall through to
+            // a session-scoped UUID, cached for the rest of this process.
+            cached = crypto.randomUUID();
+            return cached;
+        }
+        finally {
+            pending = undefined;
+        }
+    })();
+    return pending;
+}
+/**
+ * Synchronous accessor for the telemetry event path. Returns the prewarmed
+ * value when loadDeviceId() has run; otherwise falls back to a one-time
+ * synchronous read of the same file (returning the persisted id, so the value
+ * never diverges from the async path). On any IO failure, returns a one-shot
+ * UUID scoped to the current process — never throws.
+ */
+export function getDeviceId() {
+    if (cached)
+        return cached;
+    const filePath = getDeviceIdPath();
+    try {
+        if (fs.existsSync(filePath)) {
+            const raw = fs.readFileSync(filePath, 'utf8').trim();
+            if (UUID_V4_REGEX.test(raw)) {
+                cached = raw;
+                return raw;
+            }
+        }
+        const id = crypto.randomUUID();
+        fs.mkdirSync(path.dirname(filePath), { recursive: true, mode: 0o700 });
+        fs.writeFileSync(filePath, id, { encoding: 'utf8', mode: 0o600 });
+        cached = id;
+        return id;
+    }
+    catch {
+        // IO failure (readonly FS, permission denied, etc.) — fall through to
+        // a session-scoped UUID. Cache it so subsequent calls in this process
+        // return the same value; the next process run will retry IO.
+        cached = crypto.randomUUID();
+        return cached;
+    }
+}
+/** Test seam — resets the in-memory cache between test cases. */
+export function __resetDeviceIdCache() {
+    cached = undefined;
+    pending = undefined;
+}
+//# sourceMappingURL=device-id.js.map

package/dist/lib/device-id.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"device-id.js","sourceRoot":"","sources":["../../src/lib/device-id.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Persistent device identifier for telemetry correlation.\n *\n * Stored at ~/.workos/device-id as a plain UTF-8 UUID string. Not a secret\n * — this is a convenience identifier that survives keyring unavailability.\n * Any IO failure falls through to a one-shot UUID for the current session.\n */\n\nimport fs from 'node:fs';\nimport { mkdir, readFile, writeFile } from 'node:fs/promises';\nimport path from 'node:path';\nimport os from 'node:os';\nimport crypto from 'node:crypto';\n\n// RFC 4122 v4 format — matches what `crypto.randomUUID()` produces.\n// Rejects non-UUID strings like \"------------------------------------\".\nconst UUID_V4_REGEX = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;\n\nlet cached: string | undefined;\nlet pending: Promise<string> | undefined;\n\nfunction getDeviceIdPath(): string {\n  return path.join(os.homedir(), '.workos', 'device-id');\n}\n\n/**\n * Asynchronously resolve (and lazily create) the device id without blocking\n * the event loop. Memoized: the first call performs the IO, concurrent and\n * later callers await the same promise. Populates the shared cache that the\n * synchronous getDeviceId() reads, so prewarming this at startup keeps the\n * synchronous telemetry path off blocking fs IO. Never rejects.\n */\nexport function loadDeviceId(): Promise<string> {\n  if (cached) return Promise.resolve(cached);\n  if (pending) return pending;\n\n  pending = (async () => {\n    const filePath = getDeviceIdPath();\n    try {\n      try {\n        const raw = (await readFile(filePath, 'utf8')).trim();\n        if (UUID_V4_REGEX.test(raw)) {\n          cached = raw;\n          return raw;\n        }\n      } catch {\n        // Missing/unreadable file — fall through and create it.\n      }\n\n      const id = crypto.randomUUID();\n      await mkdir(path.dirname(filePath), { recursive: true, mode: 0o700 });\n      await writeFile(filePath, id, { encoding: 'utf8', mode: 0o600 });\n      cached = id;\n      return id;\n    } catch {\n      // IO failure (readonly FS, permission denied, etc.) — fall through to\n      // a session-scoped UUID, cached for the rest of this process.\n      cached = crypto.randomUUID();\n      return cached;\n    } finally {\n      pending = undefined;\n    }\n  })();\n\n  return pending;\n}\n\n/**\n * Synchronous accessor for the telemetry event path. Returns the prewarmed\n * value when loadDeviceId() has run; otherwise falls back to a one-time\n * synchronous read of the same file (returning the persisted id, so the value\n * never diverges from the async path). On any IO failure, returns a one-shot\n * UUID scoped to the current process — never throws.\n */\nexport function getDeviceId(): string {\n  if (cached) return cached;\n\n  const filePath = getDeviceIdPath();\n  try {\n    if (fs.existsSync(filePath)) {\n      const raw = fs.readFileSync(filePath, 'utf8').trim();\n      if (UUID_V4_REGEX.test(raw)) {\n        cached = raw;\n        return raw;\n      }\n    }\n\n    const id = crypto.randomUUID();\n    fs.mkdirSync(path.dirname(filePath), { recursive: true, mode: 0o700 });\n    fs.writeFileSync(filePath, id, { encoding: 'utf8', mode: 0o600 });\n    cached = id;\n    return id;\n  } catch {\n    // IO failure (readonly FS, permission denied, etc.) — fall through to\n    // a session-scoped UUID. Cache it so subsequent calls in this process\n    // return the same value; the next process run will retry IO.\n    cached = crypto.randomUUID();\n    return cached;\n  }\n}\n\n/** Test seam — resets the in-memory cache between test cases. */\nexport function __resetDeviceIdCache(): void {\n  cached = undefined;\n  pending = undefined;\n}\n"]}

package/dist/lib/preferences.d.ts

@@ -0,0 +1,101 @@
+/**
+ * Plain CLI preferences store.
+ *
+ * Stored at ~/.workos/preferences.json as plain JSON. These are NOT secrets —
+ * knowing that someone opted out of telemetry leaks nothing — so this
+ * deliberately avoids the keyring abstraction (config-store.ts) to prevent a
+ * non-secret write from ever triggering the insecure-fallback security warning.
+ *
+ * Mirrors the structural pattern of device-id.ts: a synchronous accessor backed
+ * by a cache, an async prewarm that populates that cache off the blocking-fs
+ * path, and a never-throws contract on every read/parse so a corrupt file can
+ * never break a command.
+ */
+export interface CliPreferences {
+    telemetry?: {
+        /** true => the user explicitly opted out of telemetry. */
+        optedOut?: boolean;
+        /** ISO timestamp the first-run notice was shown — written in Phase 2 only. */
+        noticeShownAt?: string;
+    };
+}
+/** Effective source of the resolved telemetry-enabled decision. */
+export type TelemetrySource = 'env' | 'preference' | 'default';
+export declare function getPreferencesPath(): string;
+/**
+ * Asynchronously load preferences and warm the cache the synchronous
+ * getPreferences() reads. Memoized: the first call performs the IO, concurrent
+ * and later callers await the same promise. Prewarming this at startup keeps
+ * the synchronous telemetry path off blocking fs IO. Never rejects.
+ */
+export declare function loadPreferences(): Promise<CliPreferences>;
+/**
+ * Synchronous accessor. Returns the prewarmed value when loadPreferences() has
+ * run; otherwise performs a one-time synchronous read of the same file. On any
+ * IO/parse failure returns {} (telemetry stays at its default-on state). Never
+ * throws.
+ */
+export declare function getPreferences(): CliPreferences;
+/**
+ * Read-modify-write the on-disk preferences, merging `next` over the current
+ * persisted value so future fields are never clobbered, then update the cache.
+ * Throws on write failure so callers on the command path (opt-out/opt-in) can
+ * surface a clear error — the read path swallows, the write path does not.
+ */
+export declare function savePreferences(next: CliPreferences): void;
+/** Whether the user has explicitly opted out via the saved preference. */
+export declare function isTelemetryOptedOut(): boolean;
+/** Persist the opt-out flag. Throws on write failure (see savePreferences). */
+export declare function setTelemetryOptedOut(value: boolean): void;
+/** Whether the first-run telemetry notice has already been shown (ever). */
+export declare function isNoticeShown(): boolean;
+/**
+ * Persist the first-run notice as shown, stamping the current time. Uses the
+ * read-modify-write savePreferences so it never clobbers the optedOut flag.
+ * Throws on write failure (see savePreferences) — the caller in
+ * telemetry-notice.ts swallows it so a read-only FS never blocks a command.
+ */
+export declare function markNoticeShown(): void;
+/**
+ * Tri-state env override for telemetry.
+ *
+ * Only the explicit strings 'true' / 'false' count as an override. Any other
+ * value — including unset or garbage like '1' — returns undefined and falls
+ * through to the saved preference.
+ *
+ * This is a deliberate, documented change from the old `WORKOS_TELEMETRY !==
+ * 'false'` behaviour: previously `WORKOS_TELEMETRY=1` forced telemetry on even
+ * for opted-out users; now an opt-out is respected unless the env var
+ * explicitly says 'true'.
+ */
+export declare function envTelemetryOverride(): boolean | undefined;
+/**
+ * Effective telemetry-enabled decision.
+ *
+ * Resolution order:
+ *   1. envTelemetryOverride() if defined — env wins in BOTH directions.
+ *   2. otherwise !isTelemetryOptedOut() — default-on unless explicitly opted out.
+ */
+export declare function isTelemetryEnabled(): boolean;
+/**
+ * Which signal produced the effective telemetry decision. Mirrors the
+ * precedence in isTelemetryEnabled() so the `telemetry status` command and the
+ * resolver can never drift.
+ *
+ * Note: an explicit opt-in (optedOut === false) reads as 'default', not
+ * 'preference' — its outcome is identical to a fresh install, and the resolver
+ * only treats optedOut === true as a non-default signal, so reporting
+ * 'preference' here would imply a behavioral difference that does not exist.
+ */
+export declare function getTelemetrySource(): TelemetrySource;
+/**
+ * Delete the preferences file, returning telemetry to its fresh-install state
+ * (opted-in, first-run notice unseen). Used by `debug reset` to wipe stored CLI
+ * state alongside credentials and config. No-op if the file does not exist;
+ * throws on a real delete failure (e.g. permission denied) so the caller can
+ * surface it, mirroring clearConfig/clearCredentials. Resets the in-memory
+ * cache so subsequent reads in this process reflect the cleared state.
+ */
+export declare function clearPreferences(): void;
+/** Test seam — resets the in-memory cache between test cases. */
+export declare function __resetPreferencesCache(): void;

package/dist/lib/preferences.js

@@ -0,0 +1,198 @@
+/**
+ * Plain CLI preferences store.
+ *
+ * Stored at ~/.workos/preferences.json as plain JSON. These are NOT secrets —
+ * knowing that someone opted out of telemetry leaks nothing — so this
+ * deliberately avoids the keyring abstraction (config-store.ts) to prevent a
+ * non-secret write from ever triggering the insecure-fallback security warning.
+ *
+ * Mirrors the structural pattern of device-id.ts: a synchronous accessor backed
+ * by a cache, an async prewarm that populates that cache off the blocking-fs
+ * path, and a never-throws contract on every read/parse so a corrupt file can
+ * never break a command.
+ */
+import fs from 'node:fs';
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import os from 'node:os';
+let cached;
+let pending;
+export function getPreferencesPath() {
+    return path.join(os.homedir(), '.workos', 'preferences.json');
+}
+function parsePreferences(raw) {
+    try {
+        const value = JSON.parse(raw);
+        // Defend against a file that parses to a non-object (e.g. `"true"`, `42`).
+        if (value && typeof value === 'object' && !Array.isArray(value)) {
+            return value;
+        }
+    }
+    catch {
+        // Corrupt JSON — fall through to empty preferences. A later savePreferences
+        // overwrites it cleanly; we never auto-delete.
+    }
+    return {};
+}
+/**
+ * Asynchronously load preferences and warm the cache the synchronous
+ * getPreferences() reads. Memoized: the first call performs the IO, concurrent
+ * and later callers await the same promise. Prewarming this at startup keeps
+ * the synchronous telemetry path off blocking fs IO. Never rejects.
+ */
+export function loadPreferences() {
+    if (cached)
+        return Promise.resolve(cached);
+    if (pending)
+        return pending;
+    pending = (async () => {
+        try {
+            const raw = await readFile(getPreferencesPath(), 'utf8');
+            cached = parsePreferences(raw);
+        }
+        catch {
+            // Missing/unreadable file — treat as no preferences set.
+            cached = {};
+        }
+        finally {
+            pending = undefined;
+        }
+        return cached;
+    })();
+    return pending;
+}
+/**
+ * Synchronous accessor. Returns the prewarmed value when loadPreferences() has
+ * run; otherwise performs a one-time synchronous read of the same file. On any
+ * IO/parse failure returns {} (telemetry stays at its default-on state). Never
+ * throws.
+ */
+export function getPreferences() {
+    if (cached)
+        return cached;
+    try {
+        const raw = fs.readFileSync(getPreferencesPath(), 'utf8');
+        cached = parsePreferences(raw);
+    }
+    catch {
+        // Missing/unreadable/corrupt — telemetry stays at its default-on state.
+        cached = {};
+    }
+    return cached;
+}
+/**
+ * Read-modify-write the on-disk preferences, merging `next` over the current
+ * persisted value so future fields are never clobbered, then update the cache.
+ * Throws on write failure so callers on the command path (opt-out/opt-in) can
+ * surface a clear error — the read path swallows, the write path does not.
+ */
+export function savePreferences(next) {
+    const filePath = getPreferencesPath();
+    // Read-modify-write over the CURRENT on-disk value (not the cache) so a field
+    // written by another process / a future phase is preserved.
+    let current = {};
+    try {
+        current = parsePreferences(fs.readFileSync(filePath, 'utf8'));
+    }
+    catch {
+        // No existing file (or unreadable) — start from empty.
+    }
+    const merged = {
+        ...current,
+        ...next,
+        ...(current.telemetry || next.telemetry ? { telemetry: { ...current.telemetry, ...next.telemetry } } : {}),
+    };
+    fs.mkdirSync(path.dirname(filePath), { recursive: true, mode: 0o700 });
+    fs.writeFileSync(filePath, JSON.stringify(merged), { encoding: 'utf8', mode: 0o600 });
+    cached = merged;
+}
+/** Whether the user has explicitly opted out via the saved preference. */
+export function isTelemetryOptedOut() {
+    return getPreferences().telemetry?.optedOut === true;
+}
+/** Persist the opt-out flag. Throws on write failure (see savePreferences). */
+export function setTelemetryOptedOut(value) {
+    savePreferences({ telemetry: { optedOut: value } });
+}
+/** Whether the first-run telemetry notice has already been shown (ever). */
+export function isNoticeShown() {
+    return !!getPreferences().telemetry?.noticeShownAt;
+}
+/**
+ * Persist the first-run notice as shown, stamping the current time. Uses the
+ * read-modify-write savePreferences so it never clobbers the optedOut flag.
+ * Throws on write failure (see savePreferences) — the caller in
+ * telemetry-notice.ts swallows it so a read-only FS never blocks a command.
+ */
+export function markNoticeShown() {
+    savePreferences({ telemetry: { noticeShownAt: new Date().toISOString() } });
+}
+/**
+ * Tri-state env override for telemetry.
+ *
+ * Only the explicit strings 'true' / 'false' count as an override. Any other
+ * value — including unset or garbage like '1' — returns undefined and falls
+ * through to the saved preference.
+ *
+ * This is a deliberate, documented change from the old `WORKOS_TELEMETRY !==
+ * 'false'` behaviour: previously `WORKOS_TELEMETRY=1` forced telemetry on even
+ * for opted-out users; now an opt-out is respected unless the env var
+ * explicitly says 'true'.
+ */
+export function envTelemetryOverride() {
+    const value = process.env.WORKOS_TELEMETRY;
+    if (value === 'true')
+        return true;
+    if (value === 'false')
+        return false;
+    return undefined;
+}
+/**
+ * Effective telemetry-enabled decision.
+ *
+ * Resolution order:
+ *   1. envTelemetryOverride() if defined — env wins in BOTH directions.
+ *   2. otherwise !isTelemetryOptedOut() — default-on unless explicitly opted out.
+ */
+export function isTelemetryEnabled() {
+    const override = envTelemetryOverride();
+    if (override !== undefined)
+        return override;
+    return !isTelemetryOptedOut();
+}
+/**
+ * Which signal produced the effective telemetry decision. Mirrors the
+ * precedence in isTelemetryEnabled() so the `telemetry status` command and the
+ * resolver can never drift.
+ *
+ * Note: an explicit opt-in (optedOut === false) reads as 'default', not
+ * 'preference' — its outcome is identical to a fresh install, and the resolver
+ * only treats optedOut === true as a non-default signal, so reporting
+ * 'preference' here would imply a behavioral difference that does not exist.
+ */
+export function getTelemetrySource() {
+    if (envTelemetryOverride() !== undefined)
+        return 'env';
+    if (isTelemetryOptedOut())
+        return 'preference';
+    return 'default';
+}
+/**
+ * Delete the preferences file, returning telemetry to its fresh-install state
+ * (opted-in, first-run notice unseen). Used by `debug reset` to wipe stored CLI
+ * state alongside credentials and config. No-op if the file does not exist;
+ * throws on a real delete failure (e.g. permission denied) so the caller can
+ * surface it, mirroring clearConfig/clearCredentials. Resets the in-memory
+ * cache so subsequent reads in this process reflect the cleared state.
+ */
+export function clearPreferences() {
+    fs.rmSync(getPreferencesPath(), { force: true });
+    cached = {};
+    pending = undefined;
+}
+/** Test seam — resets the in-memory cache between test cases. */
+export function __resetPreferencesCache() {
+    cached = undefined;
+    pending = undefined;
+}
+//# sourceMappingURL=preferences.js.map