@maximem/synap-js-sdk 0.3.0 → 0.4.1

package/dist/grpc/index.js

@@ -0,0 +1,87 @@
+import {
+  ListeningNotActiveError
+} from "../chunk-T3NZBIV2.js";
+import {
+  GrpcStreamClient,
+  PROTO_SHA
+} from "../chunk-5SC3ELNK.js";
+
+// src/grpc/index.ts
+async function checkGrpcAvailability() {
+  const isNode = typeof process !== "undefined" && process.versions?.node !== void 0 && typeof globalThis.EdgeRuntime === "undefined";
+  if (!isNode) {
+    return {
+      available: false,
+      reason: "not-node",
+      detail: "gRPC needs raw TCP and node:http2, which Edge runtimes and Workers do not provide. HTTP context fetching works normally here; only the anticipation stream is unavailable. Reaching Edge would require a gRPC-Web or Connect endpoint on the server, which does not exist yet."
+    };
+  }
+  try {
+    await import(
+      /* @vite-ignore */
+      "@grpc/grpc-js"
+    );
+    return { available: true };
+  } catch (error) {
+    return {
+      available: false,
+      reason: "module-missing",
+      detail: `@grpc/grpc-js is an optional dependency and is not installed. Run \`npm install @grpc/grpc-js\` to enable the anticipation stream. (${error?.message ?? String(error)})`
+    };
+  }
+}
+async function listen(options) {
+  if (!options.conversationId) {
+    throw new ListeningNotActiveError("conversation_id is required to start a listening stream");
+  }
+  const availability = await checkGrpcAvailability();
+  if (!availability.available) {
+    throw new ListeningNotActiveError(availability.detail);
+  }
+  const [{ GrpcStreamClient: StreamClient }, { AnticipationCache }, { getEnv }] = await Promise.all([
+    import("../stream-client-ME5N5NK4.js"),
+    import("../anticipation-cache-H7HEVWQC.js"),
+    import("../env-QCUKKW36.js")
+  ]);
+  const apiKey = options.apiKey ?? getEnv("SYNAP_API_KEY") ?? "";
+  if (apiKey === "") {
+    throw new ListeningNotActiveError(
+      "No Synap API key found. Set SYNAP_API_KEY or pass apiKey."
+    );
+  }
+  const cache = new AnticipationCache();
+  const client = new StreamClient(
+    {
+      apiKey,
+      clientId: options.clientId ?? getEnv("SYNAP_CLIENT_ID") ?? "",
+      instanceId: options.instanceId ?? getEnv("SYNAP_INSTANCE_ID") ?? ""
+    },
+    cache,
+    {
+      ...options.host !== void 0 ? { host: options.host } : {},
+      ...options.port !== void 0 ? { port: options.port } : {},
+      ...options.useTls !== void 0 ? { useTls: options.useTls } : {},
+      ...options.onBundle !== void 0 ? { onContext: options.onBundle } : {}
+    }
+  );
+  await client.connect();
+  client.sendSessionControl({
+    action: "start",
+    conversation_id: options.conversationId,
+    ...options.userId !== void 0 ? { user_id: options.userId } : {},
+    ...options.customerId !== void 0 ? { customer_id: options.customerId } : {}
+  });
+  return {
+    stop: () => client.disconnect(),
+    get active() {
+      return client.isConnected;
+    }
+  };
+}
+export {
+  GrpcStreamClient,
+  PROTO_SHA,
+  checkGrpcAvailability,
+  listen
+};
+//# sourceMappingURL=index.js.map

package/dist/grpc/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/grpc/index.ts"],"sourcesContent":["/**\n * gRPC anticipation stream: availability and loading.\n *\n * This is a SUBPATH export (`@maximem/synap-js-sdk/grpc`) and is never\n * imported by the main entry point. Three reasons, all of which have bitten\n * someone already:\n *\n *  1. `@grpc/grpc-js` plus its protos is roughly 5MB. HTTP-only and Edge users\n *     should not pay for it (gotcha G-Q).\n *  2. grpc-js is built on `node:http2`, `node:net` and `node:tls`. Merely\n *     importing it on Edge or Workers fails the *build*, not the call. Keeping\n *     it behind a subpath plus a lazy `import()` means importing the SDK on\n *     Edge stays safe.\n *  3. It is an `optionalDependency`, so it may legitimately be absent.\n *\n * ## Proto loading\n *\n * The stream is live. The proto ships as an INLINED JSON descriptor\n * (./descriptor.ts) loaded through `proto-loader.fromJSON`, not through\n * `loadSync(path)`. proto-loader's file-based path reads the `.proto` off disk\n * at runtime, which breaks under webpack/turbopack bundling and Vercel's `nft`\n * file tracing: at deploy time rather than at test time (gotcha G-P). Inlining\n * gets the same result as ts-proto codegen without a codegen toolchain.\n */\n\nimport { ListeningNotActiveError } from '../errors.js';\nexport { GrpcStreamClient } from './stream-client.js';\nexport type {\n  StreamState, StreamCredentials, StreamClientOptions, ConversationEventInput,\n} from './stream-client.js';\nexport { PROTO_SHA } from './descriptor.js';\n\nexport type GrpcAvailability =\n  | { available: true }\n  | { available: false; reason: 'not-node' | 'module-missing'; detail: string };\n\n/**\n * Whether a gRPC stream could run here.\n *\n * Deliberately does not throw: callers use this to decide whether to offer the\n * stream at all, and a hard failure at that point is unhelpful.\n */\nexport async function checkGrpcAvailability(): Promise<GrpcAvailability> {\n  const isNode =\n    typeof process !== 'undefined' &&\n    process.versions?.node !== undefined &&\n    typeof (globalThis as { EdgeRuntime?: unknown }).EdgeRuntime === 'undefined';\n\n  if (!isNode) {\n    return {\n      available: false,\n      reason: 'not-node',\n      detail:\n        'gRPC needs raw TCP and node:http2, which Edge runtimes and Workers do ' +\n        'not provide. HTTP context fetching works normally here; only the ' +\n        'anticipation stream is unavailable. Reaching Edge would require a ' +\n        'gRPC-Web or Connect endpoint on the server, which does not exist yet.',\n    };\n  }\n\n  try {\n    await import(/* @vite-ignore */ '@grpc/grpc-js');\n    return { available: true };\n  } catch (error) {\n    return {\n      available: false,\n      reason: 'module-missing',\n      detail:\n        '@grpc/grpc-js is an optional dependency and is not installed. Run ' +\n        '`npm install @grpc/grpc-js` to enable the anticipation stream. ' +\n        `(${(error as Error)?.message ?? String(error)})`,\n    };\n  }\n}\n\nexport interface ListenOptions {\n  conversationId: string;\n  userId?: string;\n  customerId?: string;\n  onBundle?: (bundle: unknown) => void;\n}\n\nexport interface ListeningSession {\n  stop(): Promise<void>;\n  readonly active: boolean;\n}\n\n/**\n * Start the anticipation stream directly, without a SynapClient.\n *\n * Most callers want `client.instance.listen()` instead, which shares the\n * client's credentials and anticipation cache. This exists for the case where\n * only the stream is wanted.\n *\n * **Opt-in, and off by default.** The removed wrapper called `listen()`\n * unconditionally during init, so every user had a stream whether they asked\n * for one or not. Making it opt-in is the right default, but it is not a\n * neutral change: fewer streams means fewer anticipation hits and therefore\n * MORE billed cloud fetches for existing users. That has to be announced\n * rather than discovered (gotcha G-Y).\n */\nexport async function listen(\n  options: ListenOptions & {\n    apiKey?: string;\n    clientId?: string;\n    instanceId?: string;\n    host?: string;\n    port?: number;\n    useTls?: boolean;\n  },\n): Promise<ListeningSession> {\n  if (!options.conversationId) {\n    // conversation_id is not a scope tier, but the stream genuinely requires\n    // one: it is what the server keys the anticipation session on.\n    throw new ListeningNotActiveError('conversation_id is required to start a listening stream');\n  }\n\n  const availability = await checkGrpcAvailability();\n  if (!availability.available) {\n    throw new ListeningNotActiveError(availability.detail);\n  }\n\n  const [{ GrpcStreamClient: StreamClient }, { AnticipationCache }, { getEnv }] = await Promise.all([\n    import('./stream-client.js'),\n    import('../context/anticipation-cache.js'),\n    import('../util/env.js'),\n  ]);\n\n  const apiKey = options.apiKey ?? getEnv('SYNAP_API_KEY') ?? '';\n  if (apiKey === '') {\n    throw new ListeningNotActiveError(\n      'No Synap API key found. Set SYNAP_API_KEY or pass apiKey.',\n    );\n  }\n\n  const cache = new AnticipationCache();\n  const client = new StreamClient(\n    {\n      apiKey,\n      clientId: options.clientId ?? getEnv('SYNAP_CLIENT_ID') ?? '',\n      instanceId: options.instanceId ?? getEnv('SYNAP_INSTANCE_ID') ?? '',\n    },\n    cache,\n    {\n      ...(options.host !== undefined ? { host: options.host } : {}),\n      ...(options.port !== undefined ? { port: options.port } : {}),\n      ...(options.useTls !== undefined ? { useTls: options.useTls } : {}),\n      ...(options.onBundle !== undefined ? { onContext: options.onBundle } : {}),\n    },\n  );\n  await client.connect();\n  client.sendSessionControl({\n    action: 'start',\n    conversation_id: options.conversationId,\n    ...(options.userId !== undefined ? { user_id: options.userId } : {}),\n    ...(options.customerId !== undefined ? { customer_id: options.customerId } : {}),\n  });\n\n  return {\n    stop: () => client.disconnect(),\n    get active() { return client.isConnected; },\n  };\n}\n"],"mappings":";;;;;;;;;AA0CA,eAAsB,wBAAmD;AACvE,QAAM,SACJ,OAAO,YAAY,eACnB,QAAQ,UAAU,SAAS,UAC3B,OAAQ,WAAyC,gBAAgB;AAEnE,MAAI,CAAC,QAAQ;AACX,WAAO;AAAA,MACL,WAAW;AAAA,MACX,QAAQ;AAAA,MACR,QACE;AAAA,IAIJ;AAAA,EACF;AAEA,MAAI;AACF,UAAM;AAAA;AAAA,MAA0B;AAAA,IAAe;AAC/C,WAAO,EAAE,WAAW,KAAK;AAAA,EAC3B,SAAS,OAAO;AACd,WAAO;AAAA,MACL,WAAW;AAAA,MACX,QAAQ;AAAA,MACR,QACE,uIAEK,OAAiB,WAAW,OAAO,KAAK,CAAC;AAAA,IAClD;AAAA,EACF;AACF;AA4BA,eAAsB,OACpB,SAQ2B;AAC3B,MAAI,CAAC,QAAQ,gBAAgB;AAG3B,UAAM,IAAI,wBAAwB,yDAAyD;AAAA,EAC7F;AAEA,QAAM,eAAe,MAAM,sBAAsB;AACjD,MAAI,CAAC,aAAa,WAAW;AAC3B,UAAM,IAAI,wBAAwB,aAAa,MAAM;AAAA,EACvD;AAEA,QAAM,CAAC,EAAE,kBAAkB,aAAa,GAAG,EAAE,kBAAkB,GAAG,EAAE,OAAO,CAAC,IAAI,MAAM,QAAQ,IAAI;AAAA,IAChG,OAAO,8BAAoB;AAAA,IAC3B,OAAO,mCAAkC;AAAA,IACzC,OAAO,oBAAgB;AAAA,EACzB,CAAC;AAED,QAAM,SAAS,QAAQ,UAAU,OAAO,eAAe,KAAK;AAC5D,MAAI,WAAW,IAAI;AACjB,UAAM,IAAI;AAAA,MACR;AAAA,IACF;AAAA,EACF;AAEA,QAAM,QAAQ,IAAI,kBAAkB;AACpC,QAAM,SAAS,IAAI;AAAA,IACjB;AAAA,MACE;AAAA,MACA,UAAU,QAAQ,YAAY,OAAO,iBAAiB,KAAK;AAAA,MAC3D,YAAY,QAAQ,cAAc,OAAO,mBAAmB,KAAK;AAAA,IACnE;AAAA,IACA;AAAA,IACA;AAAA,MACE,GAAI,QAAQ,SAAS,SAAY,EAAE,MAAM,QAAQ,KAAK,IAAI,CAAC;AAAA,MAC3D,GAAI,QAAQ,SAAS,SAAY,EAAE,MAAM,QAAQ,KAAK,IAAI,CAAC;AAAA,MAC3D,GAAI,QAAQ,WAAW,SAAY,EAAE,QAAQ,QAAQ,OAAO,IAAI,CAAC;AAAA,MACjE,GAAI,QAAQ,aAAa,SAAY,EAAE,WAAW,QAAQ,SAAS,IAAI,CAAC;AAAA,IAC1E;AAAA,EACF;AACA,QAAM,OAAO,QAAQ;AACrB,SAAO,mBAAmB;AAAA,IACxB,QAAQ;AAAA,IACR,iBAAiB,QAAQ;AAAA,IACzB,GAAI,QAAQ,WAAW,SAAY,EAAE,SAAS,QAAQ,OAAO,IAAI,CAAC;AAAA,IAClE,GAAI,QAAQ,eAAe,SAAY,EAAE,aAAa,QAAQ,WAAW,IAAI,CAAC;AAAA,EAChF,CAAC;AAED,SAAO;AAAA,IACL,MAAM,MAAM,OAAO,WAAW;AAAA,IAC9B,IAAI,SAAS;AAAE,aAAO,OAAO;AAAA,IAAa;AAAA,EAC5C;AACF;","names":[]}