@secondlayer/sdk 3.5.2 → 3.5.4

package/README.md

@@ -172,6 +172,17 @@ for await (const transfer of sl.index.ftTransfers.walk({
 
 Deploy and query app-specific L3 tables.
 
+Subgraphs and subscriptions live on per-tenant containers (`https://<slug>.api.secondlayer.tools`), not on the platform `api.secondlayer.tools`. The tenant containers expect a short-lived HS256 JWT, not your platform `sk-sl_*` key — so the SDK transparently mints one on the first subgraph or subscription call (POST `/api/tenants/me/keys/mint-ephemeral`), caches the apiUrl + JWT for the session's lifetime, and refreshes 30 s before expiry. You don't need to know the URL or manage tokens — just pass your normal `apiKey`.
+
+If you already know your tenant URL (OSS, staging, or a custom routing setup), skip the lookup with `tenantBaseUrl`:
+
+```typescript
+const sl = new SecondLayer({
+  apiKey: "sk-sl_...",
+  tenantBaseUrl: "https://myslug.api.secondlayer.tools", // optional
+});
+```
+
 ```typescript
 // List
 const { data } = await sl.subgraphs.list();
@@ -243,7 +254,14 @@ try {
 } catch (err) {
   if (err instanceof ApiError) {
     console.log(err.status);  // 404
-    console.log(err.message); // "Contract not found"
+    console.log(err.code);    // "NOT_FOUND" (from API's {error, code} envelope, if present)
+    console.log(err.message); // "Subgraph not found"
+    console.log(err.body);    // full parsed envelope
   }
 }
 ```
+
+Tenant-resolution failures surface as `ApiError` with distinctive codes:
+
+- `code: "TENANT_SUSPENDED"` — your tenant is suspended (see `err.message` for the limit reason)
+- `code: "NO_TENANT"` — your account has no provisioned tenant yet

package/dist/index.d.ts

@@ -4,23 +4,61 @@ import { SubgraphAgentSchema, SubgraphSpecOptions } from "@secondlayer/shared/su
 import { InferSubgraphClient } from "@secondlayer/subgraphs";
 type FetchLike = (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
 interface SecondLayerOptions {
-	/** Base URL of the Secondlayer API (trailing slashes are stripped). */
+	/** Base URL of the Secondlayer platform API (trailing slashes are stripped). */
 	baseUrl: string;
 	/** Bearer token for authenticated requests. */
 	apiKey?: string;
+	/**
+	* Explicit tenant API base URL — bypass the auto-resolution that calls
+	* `/api/tenants/me` on first tenant-resource request. Use when you already
+	* know your tenant URL (OSS, staging, or any custom routing setup).
+	*/
+	tenantBaseUrl?: string;
 	/** Fetch implementation. Tests and edge runtimes can provide their own. */
 	fetchImpl?: FetchLike;
 	/** Deploy origin label sent as `x-sl-origin` (telemetry). Defaults to `cli`. */
 	origin?: "cli" | "mcp" | "session";
 }
+type TenantSession = {
+	apiUrl: string
+	token: string
+	expiresAtMs: number
+};
 declare abstract class BaseClient {
 	protected baseUrl: string;
 	protected apiKey?: string;
 	protected origin: "cli" | "mcp" | "session";
+	protected tenantBaseUrlOverride?: string;
+	private _tenantSession;
+	private _tenantSessionPromise;
 	constructor(options?: Partial<SecondLayerOptions>);
 	static authHeaders(apiKey?: string): Record<string, string>;
 	protected request<T>(method: string, path: string, body?: unknown): Promise<T>;
+	protected requestAt<T>(baseUrl: string, method: string, path: string, body?: unknown, authToken?: string): Promise<T>;
 	protected requestText(method: string, path: string, body?: unknown): Promise<string>;
+	/**
+	* Resolve + cache a tenant session for tenant-resource calls (subgraphs,
+	* subscriptions). On the platform API, those routes are not mounted —
+	* they live on per-tenant containers at `https://<slug>.api.secondlayer.tools`,
+	* which expect a short-lived HS256 JWT (not the platform `sk-sl_*` key).
+	*
+	* `POST /api/tenants/me/keys/mint-ephemeral` returns both the tenant `apiUrl`
+	* and a 5-min `serviceKey` JWT in one round-trip. We cache the session and
+	* refresh before expiry. Failures are NOT cached, so a flaky platform call
+	* doesn't permanently break the SDK.
+	*
+	* Bypass via `tenantBaseUrl` constructor option for OSS / staging / custom
+	* routing where the same `apiKey` works against both surfaces.
+	*/
+	protected getTenantSession(): Promise<TenantSession>;
+	/**
+	* Returns just the tenant API base URL. Convenience wrapper around
+	* `getTenantSession` for callers that don't need the auth token (e.g. tests).
+	*/
+	protected getTenantBaseUrl(): Promise<string>;
+	private mintTenantSession;
+	protected requestAtTenant<T>(method: string, path: string, body?: unknown): Promise<T>;
+	protected requestTextAtTenant(method: string, path: string, body?: unknown): Promise<string>;
 	private fetchResponse;
 }
 interface SubgraphSource {
@@ -475,7 +513,9 @@ declare class ApiError extends Error {
 	status: number;
 	/** Raw response body (parsed JSON if possible) — preserved for callers that need error details. */
 	body?: unknown;
-	constructor(status: number, message: string, body?: unknown);
+	/** Stable machine-readable code from the API's `{error, code}` error envelope. */
+	code?: string;
+	constructor(status: number, message: string, body?: unknown, code?: string);
 }
 /**
 * Thrown on optimistic-concurrency conflict when a deploy supplies an

package/dist/index.js

@@ -2,10 +2,12 @@
 class ApiError extends Error {
   status;
   body;
-  constructor(status, message, body) {
+  code;
+  constructor(status, message, body, code) {
     super(message);
     this.status = status;
     this.body = body;
+    this.code = code;
     this.name = "ApiError";
   }
 }
@@ -23,15 +25,20 @@ class VersionConflictError extends ApiError {
 
 // src/base.ts
 var DEFAULT_BASE_URL = "https://api.secondlayer.tools";
+var TENANT_JWT_REFRESH_BUFFER_MS = 30000;
 
 class BaseClient {
   baseUrl;
   apiKey;
   origin;
+  tenantBaseUrlOverride;
+  _tenantSession = null;
+  _tenantSessionPromise = null;
   constructor(options = {}) {
     this.baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
     this.apiKey = options.apiKey;
     this.origin = options.origin ?? "cli";
+    this.tenantBaseUrlOverride = options.tenantBaseUrl?.replace(/\/+$/, "");
   }
   static authHeaders(apiKey) {
     const headers = {
@@ -43,19 +50,71 @@ class BaseClient {
     return headers;
   }
   async request(method, path, body) {
-    const response = await this.fetchResponse(method, path, body);
+    return this.requestAt(this.baseUrl, method, path, body);
+  }
+  async requestAt(baseUrl, method, path, body, authToken) {
+    const response = await this.fetchResponse(baseUrl, method, path, body, authToken);
     if (response.status === 204) {
       return;
     }
     return response.json();
   }
   async requestText(method, path, body) {
-    const response = await this.fetchResponse(method, path, body);
+    const response = await this.fetchResponse(this.baseUrl, method, path, body);
     return response.text();
   }
-  async fetchResponse(method, path, body) {
-    const url = `${this.baseUrl}${path}`;
-    const headers = BaseClient.authHeaders(this.apiKey);
+  async getTenantSession() {
+    if (this.tenantBaseUrlOverride) {
+      return {
+        apiUrl: this.tenantBaseUrlOverride,
+        token: this.apiKey ?? "",
+        expiresAtMs: Number.POSITIVE_INFINITY
+      };
+    }
+    const cached = this._tenantSession;
+    if (cached && cached.expiresAtMs - Date.now() > TENANT_JWT_REFRESH_BUFFER_MS) {
+      return cached;
+    }
+    if (!this._tenantSessionPromise) {
+      this._tenantSessionPromise = this.mintTenantSession().catch((err) => {
+        this._tenantSessionPromise = null;
+        throw err;
+      });
+    }
+    return this._tenantSessionPromise;
+  }
+  async getTenantBaseUrl() {
+    return (await this.getTenantSession()).apiUrl;
+  }
+  async mintTenantSession() {
+    const body = await this.request("POST", "/api/tenants/me/keys/mint-ephemeral");
+    if (!body.apiUrl) {
+      throw new ApiError(404, "No tenant API URL available for this account. Provision a tenant at https://secondlayer.tools/platform.", body, "NO_TENANT");
+    }
+    if (!body.serviceKey) {
+      throw new ApiError(500, "Tenant mint-ephemeral returned no serviceKey.", body, "NO_TENANT_TOKEN");
+    }
+    const session = {
+      apiUrl: body.apiUrl.replace(/\/+$/, ""),
+      token: body.serviceKey,
+      expiresAtMs: Date.parse(body.expiresAt)
+    };
+    this._tenantSession = session;
+    this._tenantSessionPromise = null;
+    return session;
+  }
+  async requestAtTenant(method, path, body) {
+    const session = await this.getTenantSession();
+    return this.requestAt(session.apiUrl, method, path, body, session.token);
+  }
+  async requestTextAtTenant(method, path, body) {
+    const session = await this.getTenantSession();
+    const response = await this.fetchResponse(session.apiUrl, method, path, body, session.token);
+    return response.text();
+  }
+  async fetchResponse(baseUrl, method, path, body, authToken) {
+    const url = `${baseUrl}${path}`;
+    const headers = BaseClient.authHeaders(authToken ?? this.apiKey);
     headers["x-sl-origin"] = this.origin;
     let response;
     try {
@@ -65,7 +124,7 @@ class BaseClient {
         body: body ? JSON.stringify(body) : undefined
       });
     } catch {
-      throw new ApiError(0, `Cannot reach API at ${this.baseUrl}. Check your connection or try again.`);
+      throw new ApiError(0, `Cannot reach API at ${baseUrl}. Check your connection or try again.`);
     }
     if (!response.ok) {
       if (response.status === 401) {
@@ -77,11 +136,12 @@ class BaseClient {
         throw new ApiError(429, msg);
       }
       if (response.status >= 500) {
-        throw new ApiError(response.status, `Server error. Try again or check status at ${this.baseUrl}/health`);
+        throw new ApiError(response.status, `Server error. Try again or check status at ${baseUrl}/health`);
       }
       const errorBody = await response.text();
       let message = `HTTP ${response.status}`;
       let parsedBody = errorBody;
+      let code;
       try {
         const json = JSON.parse(errorBody);
         parsedBody = json;
@@ -91,11 +151,14 @@ class BaseClient {
         } else if (err && typeof err === "object") {
           message = JSON.stringify(err);
         }
+        if (typeof json.code === "string") {
+          code = json.code;
+        }
       } catch {
         if (errorBody)
           message = errorBody;
       }
-      throw new ApiError(response.status, message, parsedBody);
+      throw new ApiError(response.status, message, parsedBody, code);
     }
     return response;
   }
@@ -173,28 +236,28 @@ function buildSpecQueryString(options) {
 
 class Subgraphs extends BaseClient {
   async list() {
-    return this.request("GET", "/api/subgraphs");
+    return this.requestAtTenant("GET", "/api/subgraphs");
   }
   async get(name) {
-    return this.request("GET", `/api/subgraphs/${name}`);
+    return this.requestAtTenant("GET", `/api/subgraphs/${name}`);
   }
   async openapi(name, options) {
-    return this.request("GET", `/api/subgraphs/${name}/openapi.json${buildSpecQueryString(options)}`);
+    return this.requestAtTenant("GET", `/api/subgraphs/${name}/openapi.json${buildSpecQueryString(options)}`);
   }
   async schema(name, options) {
-    return this.request("GET", `/api/subgraphs/${name}/schema.json${buildSpecQueryString(options)}`);
+    return this.requestAtTenant("GET", `/api/subgraphs/${name}/schema.json${buildSpecQueryString(options)}`);
   }
   async markdown(name, options) {
-    return this.requestText("GET", `/api/subgraphs/${name}/docs.md${buildSpecQueryString(options)}`);
+    return this.requestTextAtTenant("GET", `/api/subgraphs/${name}/docs.md${buildSpecQueryString(options)}`);
   }
   async reindex(name, options) {
-    return this.request("POST", `/api/subgraphs/${name}/reindex`, options);
+    return this.requestAtTenant("POST", `/api/subgraphs/${name}/reindex`, options);
   }
   async stop(name) {
-    return this.request("POST", `/api/subgraphs/${name}/stop`);
+    return this.requestAtTenant("POST", `/api/subgraphs/${name}/stop`);
   }
   async backfill(name, options) {
-    return this.request("POST", `/api/subgraphs/${name}/backfill`, options);
+    return this.requestAtTenant("POST", `/api/subgraphs/${name}/backfill`, options);
   }
   async gaps(name, opts) {
     const qs = new URLSearchParams;
@@ -205,27 +268,27 @@ class Subgraphs extends BaseClient {
     if (opts?.resolved !== undefined)
       qs.set("resolved", String(opts.resolved));
     const query = qs.toString();
-    return this.request("GET", `/api/subgraphs/${name}/gaps${query ? `?${query}` : ""}`);
+    return this.requestAtTenant("GET", `/api/subgraphs/${name}/gaps${query ? `?${query}` : ""}`);
   }
   async delete(name, options) {
     const qs = options?.force ? "?force=true" : "";
-    return this.request("DELETE", `/api/subgraphs/${name}${qs}`);
+    return this.requestAtTenant("DELETE", `/api/subgraphs/${name}${qs}`);
   }
   async deploy(data) {
-    return this.request("POST", "/api/subgraphs", data);
+    return this.requestAtTenant("POST", "/api/subgraphs", data);
   }
   async getSource(name) {
-    return this.request("GET", `/api/subgraphs/${name}/source`);
+    return this.requestAtTenant("GET", `/api/subgraphs/${name}/source`);
   }
   async bundle(data) {
-    return this.request("POST", "/api/subgraphs/bundle", data);
+    return this.requestAtTenant("POST", "/api/subgraphs/bundle", data);
   }
   async queryTable(name, table, params = {}) {
-    const result = await this.request("GET", `/api/subgraphs/${name}/${table}${buildSubgraphQueryString(params)}`);
+    const result = await this.requestAtTenant("GET", `/api/subgraphs/${name}/${table}${buildSubgraphQueryString(params)}`);
     return Array.isArray(result) ? result : result.data;
   }
   async queryTableCount(name, table, params = {}) {
-    return this.request("GET", `/api/subgraphs/${name}/${table}/count${buildSubgraphQueryString(params)}`);
+    return this.requestAtTenant("GET", `/api/subgraphs/${name}/${table}/count${buildSubgraphQueryString(params)}`);
   }
   typed(def) {
     const result = {};
@@ -648,40 +711,40 @@ function createStreamsClient(options) {
 // src/subscriptions/client.ts
 class Subscriptions extends BaseClient {
   async list() {
-    return this.request("GET", "/api/subscriptions");
+    return this.requestAtTenant("GET", "/api/subscriptions");
   }
   async get(id) {
-    return this.request("GET", `/api/subscriptions/${id}`);
+    return this.requestAtTenant("GET", `/api/subscriptions/${id}`);
   }
   async create(input) {
-    return this.request("POST", "/api/subscriptions", input);
+    return this.requestAtTenant("POST", "/api/subscriptions", input);
   }
   async update(id, patch) {
-    return this.request("PATCH", `/api/subscriptions/${id}`, patch);
+    return this.requestAtTenant("PATCH", `/api/subscriptions/${id}`, patch);
   }
   async pause(id) {
-    return this.request("POST", `/api/subscriptions/${id}/pause`);
+    return this.requestAtTenant("POST", `/api/subscriptions/${id}/pause`);
   }
   async resume(id) {
-    return this.request("POST", `/api/subscriptions/${id}/resume`);
+    return this.requestAtTenant("POST", `/api/subscriptions/${id}/resume`);
   }
   async delete(id) {
-    return this.request("DELETE", `/api/subscriptions/${id}`);
+    return this.requestAtTenant("DELETE", `/api/subscriptions/${id}`);
   }
   async rotateSecret(id) {
-    return this.request("POST", `/api/subscriptions/${id}/rotate-secret`);
+    return this.requestAtTenant("POST", `/api/subscriptions/${id}/rotate-secret`);
   }
   async recentDeliveries(id) {
-    return this.request("GET", `/api/subscriptions/${id}/deliveries`);
+    return this.requestAtTenant("GET", `/api/subscriptions/${id}/deliveries`);
   }
   async replay(id, range) {
-    return this.request("POST", `/api/subscriptions/${id}/replay`, range);
+    return this.requestAtTenant("POST", `/api/subscriptions/${id}/replay`, range);
   }
   async dead(id) {
-    return this.request("GET", `/api/subscriptions/${id}/dead`);
+    return this.requestAtTenant("GET", `/api/subscriptions/${id}/dead`);
   }
   async requeueDead(id, outboxId) {
-    return this.request("POST", `/api/subscriptions/${id}/dead/${outboxId}/requeue`);
+    return this.requestAtTenant("POST", `/api/subscriptions/${id}/dead/${outboxId}/requeue`);
   }
 }
 
@@ -872,5 +935,5 @@ export {
   ApiError
 };
 
-//# debugId=89BE7A17BC42C82764756E2164756E21
+//# debugId=324E81D5B88A8D7F64756E2164756E21
 //# sourceMappingURL=index.js.map