@secondlayer/sdk 3.5.1 → 3.5.3

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 SDK transparently resolves your tenant URL on the first subgraph or subscription call by hitting `/api/tenants/me` with your API key, then caches the result. You don't need to know the URL — 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,10 +4,16 @@ 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`. */
@@ -17,10 +23,28 @@ declare abstract class BaseClient {
 	protected baseUrl: string;
 	protected apiKey?: string;
 	protected origin: "cli" | "mcp" | "session";
+	protected tenantBaseUrlOverride?: string;
+	private _tenantBaseUrlPromise;
 	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): Promise<T>;
 	protected requestText(method: string, path: string, body?: unknown): Promise<string>;
+	/**
+	* Resolve and cache the tenant API base URL 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`. This method asks
+	* `/api/tenants/me` (against the platform baseUrl) for the apiUrl that
+	* belongs to the authenticated account.
+	*
+	* The result is cached on the client instance. Failures are NOT cached, so
+	* a flaky platform call doesn't permanently break the SDK.
+	*/
+	protected getTenantBaseUrl(): Promise<string>;
+	private resolveTenantBaseUrl;
+	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 +499,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";
   }
 }
@@ -28,10 +30,13 @@ class BaseClient {
   baseUrl;
   apiKey;
   origin;
+  tenantBaseUrlOverride;
+  _tenantBaseUrlPromise = 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,18 +48,53 @@ 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) {
+    const response = await this.fetchResponse(baseUrl, method, path, body);
     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();
+  }
+  getTenantBaseUrl() {
+    if (this.tenantBaseUrlOverride) {
+      return Promise.resolve(this.tenantBaseUrlOverride);
+    }
+    if (!this._tenantBaseUrlPromise) {
+      this._tenantBaseUrlPromise = this.resolveTenantBaseUrl().catch((err) => {
+        this._tenantBaseUrlPromise = null;
+        throw err;
+      });
+    }
+    return this._tenantBaseUrlPromise;
+  }
+  async resolveTenantBaseUrl() {
+    const body = await this.request("GET", "/api/tenants/me");
+    const tenant = body.tenant;
+    if (tenant.suspendedAt) {
+      throw new ApiError(403, `Tenant ${tenant.slug} is suspended${tenant.limitReason ? `: ${tenant.limitReason}` : ""}.`, body, "TENANT_SUSPENDED");
+    }
+    if (!tenant.apiUrl) {
+      throw new ApiError(404, "No tenant API URL available for this account. Provision a tenant at https://secondlayer.tools/platform.", body, "NO_TENANT");
+    }
+    return tenant.apiUrl.replace(/\/+$/, "");
+  }
+  async requestAtTenant(method, path, body) {
+    const tenantUrl = await this.getTenantBaseUrl();
+    return this.requestAt(tenantUrl, method, path, body);
+  }
+  async requestTextAtTenant(method, path, body) {
+    const tenantUrl = await this.getTenantBaseUrl();
+    const response = await this.fetchResponse(tenantUrl, method, path, body);
     return response.text();
   }
-  async fetchResponse(method, path, body) {
-    const url = `${this.baseUrl}${path}`;
+  async fetchResponse(baseUrl, method, path, body) {
+    const url = `${baseUrl}${path}`;
     const headers = BaseClient.authHeaders(this.apiKey);
     headers["x-sl-origin"] = this.origin;
     let response;
@@ -65,7 +105,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 +117,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 +132,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 +217,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 +249,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 +692,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`);
   }
 }
 
@@ -775,6 +819,13 @@ function requireString2(payload, field) {
   return value;
 }
 function requireHexValue(payload) {
+  const rawValue = payload.raw_value;
+  if (typeof rawValue === "string") {
+    if (!/^0x[0-9a-fA-F]*$/.test(rawValue)) {
+      throw new Error("nft_transfer payload has malformed value");
+    }
+    return rawValue;
+  }
   const value = payload.value;
   const hex = typeof value === "string" ? value : value && typeof value === "object" && typeof value.hex === "string" ? value.hex : null;
   if (!hex) {
@@ -865,5 +916,5 @@ export {
   ApiError
 };
 
-//# debugId=B2B1ED63B1AB801664756E2164756E21
+//# debugId=AA41F0EF16B7740B64756E2164756E21
 //# sourceMappingURL=index.js.map