@nominalso/vibe-host 0.5.0 → 0.5.1

package/dist/index.cjs

@@ -27,7 +27,7 @@ __export(index_exports, {
 module.exports = __toCommonJS(index_exports);
 
 // package.json
-var version = "0.5.0";
+var version = "0.5.1";
 
 // ../protocol-types/dist/index.js
 function normalizeSubroute(subroute) {
@@ -58,20 +58,46 @@ function isBridgeMessage(data) {
   if (CORRELATED_KINDS_SET.has(d.kind) && typeof d.requestId !== "string") return false;
   return true;
 }
+var BRIDGE_ERROR_BRAND = /* @__PURE__ */ Symbol.for("@nominalso/vibe-bridge:BridgeError");
+var HTTP_BRIDGE_ERROR_BRAND = /* @__PURE__ */ Symbol.for("@nominalso/vibe-bridge:HttpBridgeError");
 var BridgeError = class extends Error {
   constructor(code, message) {
     super(message);
     this.code = code;
     this.name = "BridgeError";
   }
+  /**
+   * Cross-realm-safe type guard. Prefer this over `instanceof BridgeError` when
+   * an error may have been thrown by a differently-built copy of the SDK (e.g.
+   * server bundle vs client bundle) — it matches on a process-global brand
+   * rather than class identity.
+   */
+  static isBridgeError(err) {
+    return typeof err === "object" && err !== null && err[BRIDGE_ERROR_BRAND] === true;
+  }
 };
+Object.defineProperty(BridgeError.prototype, BRIDGE_ERROR_BRAND, {
+  value: true,
+  enumerable: false
+});
 var HttpBridgeError = class extends BridgeError {
   constructor(status, message) {
     super("REQUEST_FAILED", message);
     this.status = status;
     this.name = "HttpBridgeError";
   }
+  /**
+   * Cross-realm-safe type guard (see {@link BridgeError.isBridgeError}). Returns
+   * `true` only for `HttpBridgeError` instances, not plain `BridgeError`s.
+   */
+  static isHttpBridgeError(err) {
+    return typeof err === "object" && err !== null && err[HTTP_BRIDGE_ERROR_BRAND] === true;
+  }
 };
+Object.defineProperty(HttpBridgeError.prototype, HTTP_BRIDGE_ERROR_BRAND, {
+  value: true,
+  enumerable: false
+});
 function isOriginPattern(entry) {
   return entry.includes("*");
 }

package/dist/index.d.cts

@@ -3265,6 +3265,28 @@ interface ContextPayload {
     hostVersion: string;
 }
 
+/**
+ * Response type for operations whose Nominal OpenAPI `200` response declares
+ * **no content schema**. hey-api generates `200: unknown` for these, so there is
+ * genuinely no concrete type to narrow to at codegen time — the shape is
+ * undocumented upstream, not merely unmapped by this SDK.
+ *
+ * We surface this named alias instead of a bare `unknown` so the gap is
+ * self-documenting: editors show `UntypedApiResponse` (with this doc) rather than
+ * an anonymous `unknown`, signalling that the value must be explicitly asserted
+ * to a known shape (`const p = res as MyPeriod`) rather than trusted. It stays
+ * assignment-compatible with `unknown`, so no runtime or narrowing behaviour
+ * changes.
+ *
+ * The fix is upstream: document these endpoints' response bodies in the owning
+ * Nominal service's OpenAPI (then the registry entry can reference the generated
+ * `*Response` type). Affected ops today: `GET_PERIODS`, `GET_PERIOD_INSTANCE`,
+ * `GET_PERIOD_INSTANCE_BY_SLUG`, `POST_TASK_OUTPUT`, `GET_TASK_INSTANCE`,
+ * `GET_TASK_INSTANCES`, `GET_TASK_DEFINITION`, `GET_ACTIVITY_DEFINITION(S)`,
+ * `GET_ACTIVITY_INSTANCE`, `GET_ACTIVITY_INSTANCE_TASKS`,
+ * `GET_ACTIVITY_PERIOD_TASKS`.
+ */
+type UntypedApiResponse = unknown;
 interface UploadPayload {
     buffer: ArrayBuffer;
     fileName: string;
@@ -3337,11 +3359,11 @@ interface RequestRegistry {
     };
     GET_PERIODS: {
         payload: Omit<GetPeriodInstancesApiActivityPeriodInstanceGetData, 'url'>;
-        data: unknown;
+        data: UntypedApiResponse;
     };
     POST_TASK_OUTPUT: {
         payload: Omit<UpdateTaskInstanceApiActivityTaskInstanceTaskInstanceIdPutData, 'url'>;
-        data: unknown;
+        data: UntypedApiResponse;
     };
     GET_DIMENSIONS: {
         payload: Omit<GetDimensionsApiAccountingDimensionGetData, 'url'>;
@@ -3357,7 +3379,7 @@ interface RequestRegistry {
     };
     GET_ACTIVITY_DEFINITIONS: {
         payload: Omit<GetActivityDefinitionsApiActivityActivityDefinitionGetData, 'url'>;
-        data: unknown;
+        data: UntypedApiResponse;
     };
     GET_TASK_DEFINITIONS: {
         payload: Omit<GetAllTasksDefinitionsApiActivityTaskDefinitionGetData, 'url'>;
@@ -3365,7 +3387,7 @@ interface RequestRegistry {
     };
     GET_TASK_INSTANCES: {
         payload: Omit<GetAllTaskInstancesApiActivityTaskInstanceGetData, 'url'>;
-        data: unknown;
+        data: UntypedApiResponse;
     };
     GET_FISCAL_CALENDARS: {
         payload: Omit<GetFiscalCalendarsBySubsidiaryApiPeriodManagerFiscalCalendarBySubsidiarySubsidiaryIdGetData, 'url'>;
@@ -3433,11 +3455,11 @@ interface RequestRegistry {
     };
     GET_PERIOD_INSTANCE: {
         payload: Omit<GetPeriodInstanceApiActivityPeriodInstancePeriodInstanceIdGetData, 'url'>;
-        data: unknown;
+        data: UntypedApiResponse;
     };
     GET_PERIOD_INSTANCE_BY_SLUG: {
         payload: Omit<GetPeriodInstanceBySlugApiActivityPeriodInstanceBySlugPeriodDisplayIdGetData, 'url'>;
-        data: unknown;
+        data: UntypedApiResponse;
     };
     GET_PERIOD_PROGRESS_BREAKDOWN: {
         payload: Omit<GetPeriodInstanceProgressBreakdownBySlugApiActivityPeriodInstanceBySlugPeriodDisplayIdProgressBreakdownGetData, 'url'>;
@@ -3445,7 +3467,7 @@ interface RequestRegistry {
     };
     GET_ACTIVITY_DEFINITION: {
         payload: Omit<GetActivityDefinitionByIdApiActivityActivityDefinitionActivityDefinitionIdGetData, 'url'>;
-        data: unknown;
+        data: UntypedApiResponse;
     };
     GET_ACTIVITY_INSTANCES: {
         payload: Omit<GetActivityInstancesApiActivityActivityInstanceGetData, 'url'>;
@@ -3453,7 +3475,7 @@ interface RequestRegistry {
     };
     GET_ACTIVITY_INSTANCE: {
         payload: Omit<GetActivityInstanceApiActivityActivityInstanceActivityInstanceIdGetData, 'url'>;
-        data: unknown;
+        data: UntypedApiResponse;
     };
     GET_ACTIVITY_INSTANCE_BY_PERIOD: {
         payload: Omit<GetActivityInstanceByPeriodApiActivityActivityInstanceByPeriodPeriodDisplayIdActivityDefinitionIdGetData, 'url'>;
@@ -3461,15 +3483,15 @@ interface RequestRegistry {
     };
     GET_ACTIVITY_INSTANCE_TASKS: {
         payload: Omit<GetTaskInstancesByActivityApiActivityActivityInstanceActivityInstanceIdTaskGetData, 'url'>;
-        data: unknown;
+        data: UntypedApiResponse;
     };
     GET_ACTIVITY_PERIOD_TASKS: {
         payload: Omit<GetTaskInstancesByActivityPeriodApiActivityActivityInstanceByPeriodPeriodDisplayIdActivityDefinitionIdTaskGetData, 'url'>;
-        data: unknown;
+        data: UntypedApiResponse;
     };
     GET_TASK_DEFINITION: {
         payload: Omit<GetTaskDefinitionByIdApiActivityTaskDefinitionTaskDefinitionIdGetData, 'url'>;
-        data: unknown;
+        data: UntypedApiResponse;
     };
     CREATE_TASK_DEFINITION: {
         payload: Omit<CreateTaskDefinitionApiActivityTaskDefinitionPostData, 'url'>;
@@ -3485,7 +3507,7 @@ interface RequestRegistry {
     };
     GET_TASK_INSTANCE: {
         payload: Omit<GetTaskInstanceByIdApiActivityTaskInstanceTaskInstanceIdGetData, 'url'>;
-        data: unknown;
+        data: UntypedApiResponse;
     };
     GET_TASK_INSTANCES_BY_FILTER: {
         payload: Omit<GetAllTaskInstancesByFilterApiActivityTaskInstanceQueryPostData, 'url'>;
@@ -3545,12 +3567,24 @@ type RequestHandlers = {
  * string-matching `error.message`. A failed Nominal API call rehydrates as the
  * {@link HttpBridgeError} subtype, which adds the HTTP `status`.
  *
+ * SDK-originated codes you may also see: `'TIMEOUT'` (a request or the connect
+ * handshake timed out), `'DESTROYED'` (the bridge was torn down mid-flight),
+ * `'PARENT_ORIGIN_UNRESOLVED'` (no embedding origin could be resolved) and
+ * `'SERVER_ENVIRONMENT'` (a browser-only method was called where there is no
+ * `window` — e.g. during SSR / in a React Server Component / in a Worker).
+ *
+ * This class is safe to import from any environment (see the module header).
+ *
  * @example
  * ```ts
+ * import { BridgeError } from '@nominalso/vibe-bridge'
+ *
  * try {
  *   await bridge.getAccounts({})
  * } catch (err) {
- *   if (err instanceof BridgeError && err.code === 'RATE_LIMITED') {
+ *   // `instanceof` works within a single bundle; `isBridgeError` also works
+ *   // across independently-built server/client bundles.
+ *   if (BridgeError.isBridgeError(err) && err.code === 'RATE_LIMITED') {
  *     // back off and retry
  *   }
  * }
@@ -3559,6 +3593,13 @@ type RequestHandlers = {
 declare class BridgeError extends Error {
     readonly code: string;
     constructor(code: string, message: string);
+    /**
+     * Cross-realm-safe type guard. Prefer this over `instanceof BridgeError` when
+     * an error may have been thrown by a differently-built copy of the SDK (e.g.
+     * server bundle vs client bundle) — it matches on a process-global brand
+     * rather than class identity.
+     */
+    static isBridgeError(err: unknown): err is BridgeError;
 }
 /**
  * A {@link BridgeError} for a failed Nominal API call. Its `code` is always
@@ -3568,10 +3609,12 @@ declare class BridgeError extends Error {
  *
  * @example
  * ```ts
+ * import { HttpBridgeError } from '@nominalso/vibe-bridge'
+ *
  * try {
  *   await bridge.getAccount({ path: { account_id: 'missing' } })
  * } catch (err) {
- *   if (err instanceof HttpBridgeError && err.status === 404) {
+ *   if (HttpBridgeError.isHttpBridgeError(err) && err.status === 404) {
  *     // handle not-found
  *   }
  * }
@@ -3580,6 +3623,11 @@ declare class BridgeError extends Error {
 declare class HttpBridgeError extends BridgeError {
     readonly status: number;
     constructor(status: number, message: string);
+    /**
+     * Cross-realm-safe type guard (see {@link BridgeError.isBridgeError}). Returns
+     * `true` only for `HttpBridgeError` instances, not plain `BridgeError`s.
+     */
+    static isHttpBridgeError(err: unknown): err is HttpBridgeError;
 }
 
 interface VibeApiClientOptions {

package/dist/index.d.ts

@@ -3265,6 +3265,28 @@ interface ContextPayload {
     hostVersion: string;
 }
 
+/**
+ * Response type for operations whose Nominal OpenAPI `200` response declares
+ * **no content schema**. hey-api generates `200: unknown` for these, so there is
+ * genuinely no concrete type to narrow to at codegen time — the shape is
+ * undocumented upstream, not merely unmapped by this SDK.
+ *
+ * We surface this named alias instead of a bare `unknown` so the gap is
+ * self-documenting: editors show `UntypedApiResponse` (with this doc) rather than
+ * an anonymous `unknown`, signalling that the value must be explicitly asserted
+ * to a known shape (`const p = res as MyPeriod`) rather than trusted. It stays
+ * assignment-compatible with `unknown`, so no runtime or narrowing behaviour
+ * changes.
+ *
+ * The fix is upstream: document these endpoints' response bodies in the owning
+ * Nominal service's OpenAPI (then the registry entry can reference the generated
+ * `*Response` type). Affected ops today: `GET_PERIODS`, `GET_PERIOD_INSTANCE`,
+ * `GET_PERIOD_INSTANCE_BY_SLUG`, `POST_TASK_OUTPUT`, `GET_TASK_INSTANCE`,
+ * `GET_TASK_INSTANCES`, `GET_TASK_DEFINITION`, `GET_ACTIVITY_DEFINITION(S)`,
+ * `GET_ACTIVITY_INSTANCE`, `GET_ACTIVITY_INSTANCE_TASKS`,
+ * `GET_ACTIVITY_PERIOD_TASKS`.
+ */
+type UntypedApiResponse = unknown;
 interface UploadPayload {
     buffer: ArrayBuffer;
     fileName: string;
@@ -3337,11 +3359,11 @@ interface RequestRegistry {
     };
     GET_PERIODS: {
         payload: Omit<GetPeriodInstancesApiActivityPeriodInstanceGetData, 'url'>;
-        data: unknown;
+        data: UntypedApiResponse;
     };
     POST_TASK_OUTPUT: {
         payload: Omit<UpdateTaskInstanceApiActivityTaskInstanceTaskInstanceIdPutData, 'url'>;
-        data: unknown;
+        data: UntypedApiResponse;
     };
     GET_DIMENSIONS: {
         payload: Omit<GetDimensionsApiAccountingDimensionGetData, 'url'>;
@@ -3357,7 +3379,7 @@ interface RequestRegistry {
     };
     GET_ACTIVITY_DEFINITIONS: {
         payload: Omit<GetActivityDefinitionsApiActivityActivityDefinitionGetData, 'url'>;
-        data: unknown;
+        data: UntypedApiResponse;
     };
     GET_TASK_DEFINITIONS: {
         payload: Omit<GetAllTasksDefinitionsApiActivityTaskDefinitionGetData, 'url'>;
@@ -3365,7 +3387,7 @@ interface RequestRegistry {
     };
     GET_TASK_INSTANCES: {
         payload: Omit<GetAllTaskInstancesApiActivityTaskInstanceGetData, 'url'>;
-        data: unknown;
+        data: UntypedApiResponse;
     };
     GET_FISCAL_CALENDARS: {
         payload: Omit<GetFiscalCalendarsBySubsidiaryApiPeriodManagerFiscalCalendarBySubsidiarySubsidiaryIdGetData, 'url'>;
@@ -3433,11 +3455,11 @@ interface RequestRegistry {
     };
     GET_PERIOD_INSTANCE: {
         payload: Omit<GetPeriodInstanceApiActivityPeriodInstancePeriodInstanceIdGetData, 'url'>;
-        data: unknown;
+        data: UntypedApiResponse;
     };
     GET_PERIOD_INSTANCE_BY_SLUG: {
         payload: Omit<GetPeriodInstanceBySlugApiActivityPeriodInstanceBySlugPeriodDisplayIdGetData, 'url'>;
-        data: unknown;
+        data: UntypedApiResponse;
     };
     GET_PERIOD_PROGRESS_BREAKDOWN: {
         payload: Omit<GetPeriodInstanceProgressBreakdownBySlugApiActivityPeriodInstanceBySlugPeriodDisplayIdProgressBreakdownGetData, 'url'>;
@@ -3445,7 +3467,7 @@ interface RequestRegistry {
     };
     GET_ACTIVITY_DEFINITION: {
         payload: Omit<GetActivityDefinitionByIdApiActivityActivityDefinitionActivityDefinitionIdGetData, 'url'>;
-        data: unknown;
+        data: UntypedApiResponse;
     };
     GET_ACTIVITY_INSTANCES: {
         payload: Omit<GetActivityInstancesApiActivityActivityInstanceGetData, 'url'>;
@@ -3453,7 +3475,7 @@ interface RequestRegistry {
     };
     GET_ACTIVITY_INSTANCE: {
         payload: Omit<GetActivityInstanceApiActivityActivityInstanceActivityInstanceIdGetData, 'url'>;
-        data: unknown;
+        data: UntypedApiResponse;
     };
     GET_ACTIVITY_INSTANCE_BY_PERIOD: {
         payload: Omit<GetActivityInstanceByPeriodApiActivityActivityInstanceByPeriodPeriodDisplayIdActivityDefinitionIdGetData, 'url'>;
@@ -3461,15 +3483,15 @@ interface RequestRegistry {
     };
     GET_ACTIVITY_INSTANCE_TASKS: {
         payload: Omit<GetTaskInstancesByActivityApiActivityActivityInstanceActivityInstanceIdTaskGetData, 'url'>;
-        data: unknown;
+        data: UntypedApiResponse;
     };
     GET_ACTIVITY_PERIOD_TASKS: {
         payload: Omit<GetTaskInstancesByActivityPeriodApiActivityActivityInstanceByPeriodPeriodDisplayIdActivityDefinitionIdTaskGetData, 'url'>;
-        data: unknown;
+        data: UntypedApiResponse;
     };
     GET_TASK_DEFINITION: {
         payload: Omit<GetTaskDefinitionByIdApiActivityTaskDefinitionTaskDefinitionIdGetData, 'url'>;
-        data: unknown;
+        data: UntypedApiResponse;
     };
     CREATE_TASK_DEFINITION: {
         payload: Omit<CreateTaskDefinitionApiActivityTaskDefinitionPostData, 'url'>;
@@ -3485,7 +3507,7 @@ interface RequestRegistry {
     };
     GET_TASK_INSTANCE: {
         payload: Omit<GetTaskInstanceByIdApiActivityTaskInstanceTaskInstanceIdGetData, 'url'>;
-        data: unknown;
+        data: UntypedApiResponse;
     };
     GET_TASK_INSTANCES_BY_FILTER: {
         payload: Omit<GetAllTaskInstancesByFilterApiActivityTaskInstanceQueryPostData, 'url'>;
@@ -3545,12 +3567,24 @@ type RequestHandlers = {
  * string-matching `error.message`. A failed Nominal API call rehydrates as the
  * {@link HttpBridgeError} subtype, which adds the HTTP `status`.
  *
+ * SDK-originated codes you may also see: `'TIMEOUT'` (a request or the connect
+ * handshake timed out), `'DESTROYED'` (the bridge was torn down mid-flight),
+ * `'PARENT_ORIGIN_UNRESOLVED'` (no embedding origin could be resolved) and
+ * `'SERVER_ENVIRONMENT'` (a browser-only method was called where there is no
+ * `window` — e.g. during SSR / in a React Server Component / in a Worker).
+ *
+ * This class is safe to import from any environment (see the module header).
+ *
  * @example
  * ```ts
+ * import { BridgeError } from '@nominalso/vibe-bridge'
+ *
  * try {
  *   await bridge.getAccounts({})
  * } catch (err) {
- *   if (err instanceof BridgeError && err.code === 'RATE_LIMITED') {
+ *   // `instanceof` works within a single bundle; `isBridgeError` also works
+ *   // across independently-built server/client bundles.
+ *   if (BridgeError.isBridgeError(err) && err.code === 'RATE_LIMITED') {
  *     // back off and retry
  *   }
  * }
@@ -3559,6 +3593,13 @@ type RequestHandlers = {
 declare class BridgeError extends Error {
     readonly code: string;
     constructor(code: string, message: string);
+    /**
+     * Cross-realm-safe type guard. Prefer this over `instanceof BridgeError` when
+     * an error may have been thrown by a differently-built copy of the SDK (e.g.
+     * server bundle vs client bundle) — it matches on a process-global brand
+     * rather than class identity.
+     */
+    static isBridgeError(err: unknown): err is BridgeError;
 }
 /**
  * A {@link BridgeError} for a failed Nominal API call. Its `code` is always
@@ -3568,10 +3609,12 @@ declare class BridgeError extends Error {
  *
  * @example
  * ```ts
+ * import { HttpBridgeError } from '@nominalso/vibe-bridge'
+ *
  * try {
  *   await bridge.getAccount({ path: { account_id: 'missing' } })
  * } catch (err) {
- *   if (err instanceof HttpBridgeError && err.status === 404) {
+ *   if (HttpBridgeError.isHttpBridgeError(err) && err.status === 404) {
  *     // handle not-found
  *   }
  * }
@@ -3580,6 +3623,11 @@ declare class BridgeError extends Error {
 declare class HttpBridgeError extends BridgeError {
     readonly status: number;
     constructor(status: number, message: string);
+    /**
+     * Cross-realm-safe type guard (see {@link BridgeError.isBridgeError}). Returns
+     * `true` only for `HttpBridgeError` instances, not plain `BridgeError`s.
+     */
+    static isHttpBridgeError(err: unknown): err is HttpBridgeError;
 }
 
 interface VibeApiClientOptions {

package/dist/index.js

@@ -1,5 +1,5 @@
 // package.json
-var version = "0.5.0";
+var version = "0.5.1";
 
 // ../protocol-types/dist/index.js
 function normalizeSubroute(subroute) {
@@ -30,20 +30,46 @@ function isBridgeMessage(data) {
   if (CORRELATED_KINDS_SET.has(d.kind) && typeof d.requestId !== "string") return false;
   return true;
 }
+var BRIDGE_ERROR_BRAND = /* @__PURE__ */ Symbol.for("@nominalso/vibe-bridge:BridgeError");
+var HTTP_BRIDGE_ERROR_BRAND = /* @__PURE__ */ Symbol.for("@nominalso/vibe-bridge:HttpBridgeError");
 var BridgeError = class extends Error {
   constructor(code, message) {
     super(message);
     this.code = code;
     this.name = "BridgeError";
   }
+  /**
+   * Cross-realm-safe type guard. Prefer this over `instanceof BridgeError` when
+   * an error may have been thrown by a differently-built copy of the SDK (e.g.
+   * server bundle vs client bundle) — it matches on a process-global brand
+   * rather than class identity.
+   */
+  static isBridgeError(err) {
+    return typeof err === "object" && err !== null && err[BRIDGE_ERROR_BRAND] === true;
+  }
 };
+Object.defineProperty(BridgeError.prototype, BRIDGE_ERROR_BRAND, {
+  value: true,
+  enumerable: false
+});
 var HttpBridgeError = class extends BridgeError {
   constructor(status, message) {
     super("REQUEST_FAILED", message);
     this.status = status;
     this.name = "HttpBridgeError";
   }
+  /**
+   * Cross-realm-safe type guard (see {@link BridgeError.isBridgeError}). Returns
+   * `true` only for `HttpBridgeError` instances, not plain `BridgeError`s.
+   */
+  static isHttpBridgeError(err) {
+    return typeof err === "object" && err !== null && err[HTTP_BRIDGE_ERROR_BRAND] === true;
+  }
 };
+Object.defineProperty(HttpBridgeError.prototype, HTTP_BRIDGE_ERROR_BRAND, {
+  value: true,
+  enumerable: false
+});
 function isOriginPattern(entry) {
   return entry.includes("*");
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nominalso/vibe-host",
-  "version": "0.5.0",
+  "version": "0.5.1",
   "description": "Host-side SDK for embedding Nominal Vibe Apps — receives bridge requests over a typed postMessage protocol and dispatches them to Nominal APIs (used by nom-ui).",
   "license": "UNLICENSED",
   "homepage": "https://github.com/nominalso/vibe-apps-sdk#readme",