@secondlayer/sdk 6.13.0 → 6.15.0

package/README.md

@@ -128,6 +128,31 @@ for await (const event of streams.events.stream({
 }
 ```
 
+Real-time push (`events.subscribe`).
+
+Use `client.events.subscribe` for callback-style live delivery — it pushes each
+event to `onEvent` as it lands. It's fetch-based (so it carries the Bearer key)
+and works in browsers and Node 18+. It auto-reconnects from the last delivered
+cursor on a dropped connection, and returns an unsubscribe function.
+
+```typescript
+const unsubscribe = streams.events.subscribe({
+  types: ["ft_transfer"],          // notTypes / contractId / sender / recipient / assetIdentifier also filter
+  // fromCursor: lastCursor,       // resume strictly after this cursor; omit to tail from the tip
+  onEvent: async (event) => {
+    console.log(event.cursor, event.tx_id);
+  },
+  onError: (err) => console.error("reconnecting…", err),
+});
+
+// later
+unsubscribe(); // or pass `signal` and abort it
+```
+
+Each pushed frame is `{ event, sig, key_id }`. When the client was created with
+`verify` (or `{ publicKey }`), the per-frame ed25519 signature is checked before
+`onEvent` runs; a bad/missing signature throws `StreamsSignatureError`.
+
 Bulk parquet dumps.
 
 Finalized history is published as public parquet files. Set `dumpsBaseUrl`
@@ -135,6 +160,12 @@ Finalized history is published as public parquet files. Set `dumpsBaseUrl`
 decode parquet; `download` hands you sha256-verified bytes to process with your
 own tooling.
 
+The bulk **manifest is ed25519-signed**, and the SDK verifies that signature
+before it trusts any per-file sha256 listed in it. The `verifyDumpsManifest`
+option **defaults to `true`** — `dumps.list()` and `events.replay()` enforce it,
+so you don't trust the file hashes unless the manifest itself verifies. Opt out
+with `verifyDumpsManifest: false`.
+
 ```typescript
 const streams = createStreamsClient({
   apiKey: process.env.SL_API_KEY!,
@@ -317,6 +348,30 @@ const gaps = await sl.subgraphs.gaps("my-subgraph");
 const result = await sl.subgraphs.deploy({ name, sources, schema, handlerCode });
 ```
 
+Stream rows live with the typed client — each table exposes `subscribe`
+alongside `findMany`/`count`:
+
+```typescript
+const subgraph = sl.subgraphs.typed(myDefinition); // { transfers, ... }
+
+const unsubscribe = subgraph.transfers.subscribe(
+  (row) => console.log(row),
+  {
+    where: { amount: { gte: "1000000" } }, // optional row filter
+    since: 180000,                          // optional: replay from this block_height, then tail
+    onError: (err) => console.error(err),
+  },
+);
+
+// later
+unsubscribe();
+```
+
+`subscribe` is an SSE stream over the global `EventSource` (available in
+browsers and Node ≥ 22; it throws if no `EventSource` is present). Frames are
+unsigned rows. `since: <block_height>` replays matching rows from that height,
+then tails the live edge; omit it to tail only.
+
 ## Subscriptions
 
 Signed HTTP webhooks. Subscriptions are polymorphic — pick one kind:
@@ -396,6 +451,38 @@ const { data: dead } = await sl.subscriptions.dead(id);
 await sl.subscriptions.requeueDead(id, outboxId);
 ```
 
+### Verifying deliveries
+
+Every delivery — any kind, any `format` — also carries a universal authenticity
+signature you can verify with one published key, no per-subscription secret. The
+headers are `webhook-id`, `x-secondlayer-signature`, and
+`x-secondlayer-signature-keyid`; the signed content is `` `${webhook-id}.${rawBody}` ``
+(ed25519). Fetch the public key from `GET /public/streams/signing-key`.
+
+```typescript
+import { verifySecondlayerSignature } from "@secondlayer/sdk";
+
+app.post("/webhook", async (c) => {
+  const raw = await c.req.text(); // raw body — never re-stringify the parsed JSON
+  if (!verifySecondlayerSignature(raw, c.req.raw.headers, SECONDLAYER_PUBLIC_KEY)) {
+    return c.text("Invalid signature", 401);
+  }
+  // ... trusted ...
+  return c.body(null, 204);
+});
+```
+
+```typescript
+verifySecondlayerSignature(
+  rawBody: string,
+  headers: WebhookHeaderInput,   // plain object, Fetch `Headers`, or a lookup fn
+  publicKeyPem: string,
+): boolean;
+```
+
+Prefer the per-subscription HMAC (Standard Webhooks) secret instead? Use
+`verifyWebhookSignature(rawBody, headers, secret)` — raw body first.
+
 ## Error Handling
 
 ```typescript

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { ReindexResponse, SubgraphDetail, SubgraphGapsResponse, SubgraphQueryParams, SubgraphSummary } from "@secondlayer/shared/schemas";
+import { ReindexResponse, SubgraphAggregateParams, SubgraphAggregateResponse, SubgraphDetail, SubgraphGapsResponse, SubgraphQueryParams, SubgraphSummary } from "@secondlayer/shared/schemas";
 import { DeploySubgraphRequest, DeploySubgraphResponse } from "@secondlayer/shared/schemas/subgraphs";
 import { SubgraphAgentSchema, SubgraphSpecOptions } from "@secondlayer/shared/subgraphs/spec";
 import { InferSubgraphClient } from "@secondlayer/subgraphs";
@@ -110,6 +110,7 @@ declare class Subgraphs extends BaseClient {
 	queryTableCount(name: string, table: string, params?: SubgraphQueryParams): Promise<{
 		count: number
 	}>;
+	queryTableAggregate(name: string, table: string, params?: SubgraphAggregateParams): Promise<SubgraphAggregateResponse>;
 	/**
 	* Returns a typed client for a subgraph defined with `defineSubgraph()`.
 	* Row types are inferred from the subgraph's schema literal types.
@@ -1014,6 +1015,14 @@ type StreamsTip = {
 	*/
 	finalized_height?: number
 	lag_seconds: number
+	/**
+	* Oldest height still seekable on the live API for the caller's tier
+	* (`tip - retention`). `null` = unlimited retention. Older reads must use the
+	* cold dumps lane. Optional for back-compat.
+	*/
+	oldest_seekable_height?: number | null
+	/** Oldest seekable cursor (`<oldest_seekable_height>:0`); `null` = unlimited. */
+	oldest_cursor?: string | null
 };
 type StreamsCanonicalBlock = {
 	block_height: number
@@ -1274,7 +1283,7 @@ type StreamsUsage = {
 		events_this_month: number
 	}
 };
-import { CreateSubscriptionRequest, CreateSubscriptionResponse, DeadRow, DeliveryRow, ReplayResult, RotateSecretResponse, SubscriptionDetail, SubscriptionSummary, UpdateSubscriptionRequest } from "@secondlayer/shared/schemas/subscriptions";
+import { CreateSubscriptionRequest, CreateSubscriptionResponse, DeadRow, DeliveryRow, ReplayResult, RotateSecretResponse, SubscriptionDetail, SubscriptionSummary, SubscriptionTestResult, UpdateSubscriptionRequest } from "@secondlayer/shared/schemas/subscriptions";
 import { ChainTrigger, ChainTriggerType, CreateSubscriptionRequest as CreateSubscriptionRequest2, CreateSubscriptionResponse as CreateSubscriptionResponse2, DeadRow as DeadRow2, DeliveryRow as DeliveryRow2, ReplayResult as ReplayResult2, RotateSecretResponse as RotateSecretResponse2, SubscriptionDetail as SubscriptionDetail2, SubscriptionFormat, SubscriptionKind, SubscriptionRuntime, SubscriptionStatus, SubscriptionSummary as SubscriptionSummary2, UpdateSubscriptionRequest as UpdateSubscriptionRequest2 } from "@secondlayer/shared/schemas/subscriptions";
 import { trigger } from "@secondlayer/shared/schemas/subscriptions";
 declare class Subscriptions extends BaseClient {
@@ -1290,6 +1299,9 @@ declare class Subscriptions extends BaseClient {
 		ok: true
 	}>;
 	rotateSecret(id: string): Promise<RotateSecretResponse>;
+	/** Send a one-off test webhook to the subscription's URL (built for its
+	*  format, SSRF-guarded). Logged as a delivery row, visible via recentDeliveries. */
+	test(id: string): Promise<SubscriptionTestResult>;
 	recentDeliveries(id: string): Promise<{
 		data: DeliveryRow[]
 	}>;

package/dist/index.js

@@ -194,6 +194,26 @@ function buildSubgraphQueryString(params) {
   const str = qs.toString();
   return str ? `?${str}` : "";
 }
+function buildAggregateQueryString(params) {
+  const qs = new URLSearchParams;
+  if (params.filters) {
+    for (const [key, value] of Object.entries(params.filters)) {
+      qs.set(key, String(value));
+    }
+  }
+  if (params.count)
+    qs.set("_count", "true");
+  if (params.countDistinct?.length)
+    qs.set("_countDistinct", params.countDistinct.join(","));
+  if (params.sum?.length)
+    qs.set("_sum", params.sum.join(","));
+  if (params.min?.length)
+    qs.set("_min", params.min.join(","));
+  if (params.max?.length)
+    qs.set("_max", params.max.join(","));
+  const str = qs.toString();
+  return str ? `?${str}` : "";
+}
 function buildSpecQueryString(options) {
   const qs = new URLSearchParams;
   if (options?.serverUrl)
@@ -264,6 +284,9 @@ class Subgraphs extends BaseClient {
   async queryTableCount(name, table, params = {}) {
     return this.request("GET", `/api/subgraphs/${name}/${table}/count${buildSubgraphQueryString(params)}`);
   }
+  async queryTableAggregate(name, table, params = {}) {
+    return this.request("GET", `/api/subgraphs/${name}/${table}/aggregate${buildAggregateQueryString(params)}`);
+  }
   typed(def) {
     const result = {};
     for (const tableName of Object.keys(def.schema)) {
@@ -302,6 +325,18 @@ class Subgraphs extends BaseClient {
         });
         return result.count;
       },
+      async aggregate(spec) {
+        const filters = spec.where ? serializeWhere(spec.where) : undefined;
+        const result = await self.queryTableAggregate(subgraphName, tableName, {
+          filters,
+          count: spec.count,
+          countDistinct: spec.countDistinct,
+          sum: spec.sum,
+          min: spec.min,
+          max: spec.max
+        });
+        return result;
+      },
       subscribe(onRow, options = {}) {
         const filters = options.where ? serializeWhere(options.where) : {};
         const qs = new URLSearchParams;
@@ -1542,6 +1577,9 @@ class Subscriptions extends BaseClient {
   async rotateSecret(id) {
     return this.request("POST", `/api/subscriptions/${id}/rotate-secret`);
   }
+  async test(id) {
+    return this.request("POST", `/api/subscriptions/${id}/test`);
+  }
   async recentDeliveries(id) {
     return this.request("GET", `/api/subscriptions/${id}/deliveries`);
   }
@@ -2090,5 +2128,5 @@ export {
   ApiError
 };
 
-//# debugId=5E490BEDE2791EFC64756E2164756E21
+//# debugId=4980F60DADD3DFA064756E2164756E21
 //# sourceMappingURL=index.js.map