@heedeo/sdk 0.1.0-pilot.4 → 0.1.0-pilot.5

package/README.md

@@ -108,7 +108,12 @@ Use HTTPS for deployed testing, including Safari's secure-cookie behavior. Revie
 
 Server options: `secretKey`, required `clientIp(request)`, optional `path` (default `/hd`), `timeoutMs` (default 3000 total across event retries), `baseUrl` (default `https://app.heedeo.com`), and `fetch` for testing. Custom origins require HTTPS, except localhost. Browser options: `publishableKey`, matching `path`, and `timeoutMs` (default 3000 total for script loading and identification).
 
-Configuration mistakes throw when you construct the client, so missing keys are caught at setup. Operational failures return `{ data: null, error: { code, message, status? } }`. Common codes are `missing_token`, `missing_client_ip`, `invalid_key`, `api_error`, `network_error`, and `timeout_or_aborted`. Neither entry point logs credentials, request bodies or upstream error bodies.
+Configuration mistakes throw when you construct the client, so missing keys are caught at setup. Operational failures return `{ data: null, error: { code, message, status? } }`; checking `error` narrows `data` to the success value. `code` is a `HeedeoErrorCode`, so a `switch` over it is checked by TypeScript:
+
+- Server: `missing_token`, `missing_client_ip`, `invalid_key`, `api_error`, `invalid_response`, `network_error`, `timeout_or_aborted`, `configuration_error`.
+- Browser: `browser_required`, `timeout`, `invalid_response`, `identification_unavailable`.
+
+Neither entry point logs credentials, request bodies or upstream error bodies.
 
 Browser timeouts stop waiting, but cannot cancel an already-running collector call in this pilot version. Always pass the returned token explicitly; never fall back to an older cookie token after a timeout. Browser results are not security decisions. Secret keys and event signals stay on your server.
 
@@ -116,11 +121,8 @@ Browser timeouts stop waiting, but cannot cancel an already-running collector ca
 
 This package is an ESM package (use `import`) for Node.js servers. The browser entry is separate and imports no server code. The server entry supports Node.js and Cloudflare Workers with `nodejs_compat`. Other edge runtimes have not been verified. No change to your hosting, database or sign-in provider is required. React hooks, server-action adapters, Express-specific wrappers and an automatic installer are not included in this release.
 
-
 ## Cloudflare Workers
 
-Cloudflare Workers is supported by the npm release.
-
 Enable `nodejs_compat` in Wrangler. Create the client inside the request handler so keys come from Worker secrets:
 
 ```ts

package/dist/browser.d.ts

@@ -1,5 +1,5 @@
 import { type Identification, type Result } from "./shared.js";
-export type { HeedeoError, Identification, Result } from "./shared.js";
+export type { HeedeoError, HeedeoErrorCode, Identification, Result } from "./shared.js";
 /** Create once per app. Calling this function alone makes no identification request. */
 export declare function createHeedeo(options: {
     publishableKey: string | undefined;

package/dist/server.d.ts

@@ -1,7 +1,7 @@
 import { type EventData } from "./response.js";
 export type { EventData } from "./response.js";
 import { type Result } from "./shared.js";
-export type { HeedeoError, Result } from "./shared.js";
+export type { HeedeoError, HeedeoErrorCode, Result } from "./shared.js";
 export type HeedeoOptions = {
     secretKey: string | undefined;
     /** Resolve only an IP supplied by your trusted hosting layer. Used for BOTH requests. */

package/dist/server.js

@@ -27,6 +27,8 @@ const EVENT_HEADERS = [
     "sec-ch-ua-platform",
     "sec-ch-ua-mobile",
 ];
+class PayloadTooLarge extends Error {
+}
 async function limitedBody(request, signal) {
     const reader = request.body?.getReader();
     if (!reader)
@@ -46,7 +48,7 @@ async function limitedBody(request, signal) {
                 break;
             size += value.byteLength;
             if (size > 65536)
-                throw new RangeError("Payload too large");
+                throw new PayloadTooLarge();
             chunks.push(value);
         }
         const body = new Uint8Array(size);
@@ -205,7 +207,7 @@ export class Heedeo {
             return new Response(response.body, { status: response.status, headers: outgoing });
         }
         catch (error) {
-            if (error instanceof RangeError)
+            if (error instanceof PayloadTooLarge)
                 return new Response("Payload too large", { status: 413 });
             return new Response("Heedeo is unavailable", {
                 status: 502,

package/dist/shared.d.ts

@@ -1,5 +1,6 @@
+export type HeedeoErrorCode = "missing_token" | "missing_client_ip" | "invalid_key" | "api_error" | "invalid_response" | "network_error" | "timeout_or_aborted" | "configuration_error" | "browser_required" | "timeout" | "identification_unavailable";
 export type HeedeoError = {
-    code: string;
+    code: HeedeoErrorCode;
     message: string;
     status?: number;
 };
@@ -10,7 +11,7 @@ export type Result<T> = {
     data: null;
     error: HeedeoError;
 };
-export declare function failure(code: string, message: string, status?: number): Result<never>;
+export declare function failure(code: HeedeoErrorCode, message: string, status?: number): Result<never>;
 export declare function timeout(value: number): number;
 export declare function pathPrefix(value: string): string;
 export type Identification = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@heedeo/sdk",
-  "version": "0.1.0-pilot.4",
+  "version": "0.1.0-pilot.5",
   "description": "Browser identification and server-side signup signals for Heedeo",
   "type": "module",
   "engines": {