@secondlayer/subgraphs 4.1.4 → 4.2.0

package/dist/src/testing/index.d.ts

@@ -119,7 +119,12 @@ type TraitScope = {
 *
 * ```ts
 * sources: {
-*   registry: { type: "print_event", contractId: REGISTRY, topic: "pool-created" },
+*   registry: {
+*     type: "print_event",
+*     contractId: REGISTRY,
+*     topic: "pool-created",
+*     prints: { "pool-created": { pool: "principal" } },
+*   },
 *   swaps: {
 *     type: "print_event",
 *     topic: "swap",
@@ -244,6 +249,9 @@ interface ContractCallFilter extends TraitScope, FactoryScope {
 	* decoded function arguments. Dev-provided; serialized into the deployed
 	* definition and used at runtime to decode args by name. Omit to keep
 	* `event.args` as a positional `unknown[]`.
+	*
+	* Deploy validation requires `abi` whenever `functionName` is set
+	* (`normalizeAbi()` from `@secondlayer/stacks/clarity`).
 	*/
 	abi?: AbiContract2;
 }
@@ -274,29 +282,70 @@ type PrintField = ColumnType | {
 } | {
 	list: PrintField
 };
-interface PrintEventFilter extends TraitScope, FactoryScope {
-	type: "print_event";
-	/** One contract id, or a set of them (max 20). Supports `*` wildcards.
-	*  COMPOSES with `trait` — the matcher ANDs them, so the pair means
-	*  "contracts conforming to this trait, narrowed to these ids". (The Index
-	*  read API refuses the combination, but that is its query planner's
-	*  constraint, not a semantic one.) */
-	contractId?: string | readonly string[];
-	topic?: string;
-	/**
-	* Per-topic field schema. When declared, the handler's `event` is a
-	* discriminated union keyed by `topic` and `event.data` is typed per topic
-	* (e.g. `{ "completed-deposit": { amount: "uint", sender: "principal" } }`).
-	* Nested tuples, lists, and optional fields are expressible — see
-	* {@link PrintField}.
-	*
-	* Declaring `prints` also opts the source into RUNTIME validation: an
-	* event whose decoded payload does not match is skipped and logged rather
-	* than written as nulls (and the deploy-time field lint is promoted from
-	* a warning to an error).
-	*/
-	prints?: Record<string, Record<string, PrintField>>;
+/**
+* Per-topic field schema for a print_event source. When declared, the handler's
+* `event` is a discriminated union keyed by `topic` and `event.data` is typed
+* per topic. Nested tuples, lists, and optional fields — see {@link PrintField}.
+*
+* Also opts the source into RUNTIME validation: a payload that does not match
+* is skipped and logged rather than written as nulls.
+*/
+type PrintEventPrints = Record<string, Record<string, PrintField>>;
+/**
+* One column in a static identity map. Literals only — the bundler never
+* executes user code, so `{ from: "tokenX" }` is valid and `from("tokenX")`
+* is not.
+*/
+type MaterializeColumn = {
+	from: string
+} | {
+	fromTx: "sender" | "txId"
+} | {
+	fromBlock: "height" | "hash" | "timestamp"
+};
+/** Static insert from a source event — replaces a 1:1 handler. */
+interface MaterializeSpec {
+	table: string;
+	/** Keys = schema column names (snake). */
+	columns: Record<string, MaterializeColumn>;
 }
+type PrintEventFields = FactoryScope & {
+	type: "print_event"
+	topic?: string
+	/** Identity map: insert without a handler function. XOR with handlers[name]. */
+	materialize?: MaterializeSpec
+};
+/**
+* Pinned to one or more contract ids with no trait — `prints` is required so
+* `event.data` is typed and empty-table handlers cannot typecheck.
+*/
+type PinnedPrintEventFilter = PrintEventFields & {
+	contractId: string | readonly string[]
+	trait?: undefined
+	prints: PrintEventPrints
+};
+/**
+* Trait-scoped print source (optionally narrowed by contractId). No single
+* schema — `prints` stays optional.
+*/
+type TraitPrintEventFilter = PrintEventFields & {
+	contractId?: string | readonly string[]
+	trait: string
+	prints?: PrintEventPrints
+};
+/**
+* Unpinned / factory-only print source (no contractId). `prints` optional.
+*/
+type UnpinnedPrintEventFilter = PrintEventFields & {
+	contractId?: undefined
+	trait?: string
+	prints?: PrintEventPrints
+};
+/**
+* Print-event filter. Pinned sources (contractId set, no trait) require
+* `prints`; trait and unpinned sources may omit it.
+*/
+type PrintEventFilter = PinnedPrintEventFilter | TraitPrintEventFilter | UnpinnedPrintEventFilter;
 /** All subgraph filter types — discriminated on `type` */
 type SubgraphFilter = StxTransferFilter | StxMintFilter | StxBurnFilter | StxLockFilter | FtTransferFilter | FtMintFilter | FtBurnFilter | NftTransferFilter | NftMintFilter | NftBurnFilter | ContractCallFilter | ContractDeployFilter | PrintEventFilter;
 /** Transaction metadata available in handlers */
@@ -636,6 +685,14 @@ interface TestSubgraphContext<S extends SubgraphSchema> extends Omit<TypedSubgra
 	commit(): Promise<void>;
 	/** Swap the transaction metadata handlers see (`ctx.tx`). */
 	setTx(tx: Partial<TxMeta2>): void;
+	/** Insert ops queued since `opsCheckpoint()`, for preview IN/OUT traces. */
+	pendingInsertsSince(checkpoint: number): Array<{
+		table: string
+		keys: string[]
+		row: Record<string, unknown>
+	}>;
+	/** Length of the pending-ops queue (same as runtime `opsCheckpoint`). */
+	opsCheckpoint(): number;
 }
 /**
 * Build an in-memory context for a subgraph's schema.
@@ -668,4 +725,118 @@ declare function createTestContext<const S extends SubgraphSchema>(schema: S, op
 declare function buildEvent<const F extends SubgraphFilter>(source: F, payload: Record<string, unknown>, options?: {
 	tx?: Partial<TxMeta2>
 }): EventForFilter<F>;
-export { createTestContext, buildEventPayload, buildEvent, TxMeta2 as TxMeta, TestSubgraphContext, BlockMeta };
+/**
+* Shared subgraph test run — payload map + in-memory handlers + fail-closed
+* EMPTY_MAPPING. CLI and MCP both call this; cassette/fetch/print stay in the
+* CLI, Index fetch stays in each caller.
+*/
+/** Structural Index event row (avoids an SDK dep on this package). */
+interface IndexEventRow {
+	event_type: string;
+	contract_id?: string | null;
+	/** Print events carry `{ topic, value }`; other types vary. */
+	payload?: unknown;
+	sender?: unknown;
+	recipient?: unknown;
+	amount?: unknown;
+	asset_identifier?: unknown;
+	value?: unknown;
+	cursor?: string;
+	[key: string]: unknown;
+}
+/** Structural Index contract-call row. */
+interface IndexContractCallRow {
+	sender: string;
+	contract_id?: string | null;
+	function_name?: string | null;
+	args?: unknown;
+	result?: unknown;
+	result_hex?: unknown;
+	tx_id: string;
+	status: string;
+	cursor?: string;
+	[key: string]: unknown;
+}
+type IndexTestRow = IndexEventRow | IndexContractCallRow;
+interface SubgraphTestSource {
+	type: string;
+	contractId?: string | string[];
+	topic?: string;
+	functionName?: string;
+}
+/** Per-event IN/OUT trace for `subgraphs preview`. */
+interface EventTrace {
+	source: string;
+	blockHeight?: number;
+	txId?: string;
+	/** Camelized event.data keys (or contract-call field names). */
+	inKeys: string[];
+	/** Tables written by this event; empty when the mapping wrote nothing. */
+	outs: Array<{
+		table: string
+		keys: string[]
+	}>;
+}
+interface SubgraphTestResult {
+	ok: boolean;
+	code?: "EMPTY_MAPPING" | "NO_EVENTS" | "NO_SOURCES";
+	matched: number;
+	written: number;
+	tables: Array<{
+		name: string
+		rows: number
+		sampleRow?: Record<string, unknown>
+	}>;
+	firstEvent?: {
+		source: string
+		data?: unknown
+	};
+	hint?: string;
+	/** Present when `trace: true`. */
+	traces?: EventTrace[];
+	/** Keys present on every matched IN and never written to any OUT column. */
+	unusedInKeys?: string[];
+}
+interface RunSubgraphTestInput {
+	schema: SubgraphSchema;
+	handlers: Record<string, unknown>;
+	sources: Record<string, SubgraphTestSource>;
+	events: Record<string, IndexTestRow[]>;
+	/** Collect per-event IN/OUT traces (preview). */
+	trace?: boolean;
+}
+/** Map an Index event row onto the payload shape a handler expects. */
+declare function toHandlerPayload(_filter: {
+	type: string
+} | undefined, row: IndexEventRow): Record<string, unknown>;
+/** Map an Index contract-call row onto the ContractCallEvent handler shape. */
+declare function toContractCallPayload(row: IndexContractCallRow): Record<string, unknown>;
+/**
+* Apply local handlers to Index rows in memory. Fail-closed: matched events
+* with zero written rows is EMPTY_MAPPING (the bns-names field-mapping shape).
+*/
+declare function runSubgraphTest(input: RunSubgraphTestInput): Promise<SubgraphTestResult>;
+interface ProbeHandlersDef {
+	schema: SubgraphSchema;
+	sources: Record<string, {
+		type: string
+		[key: string]: unknown
+	}>;
+	handlers: Record<string, unknown>;
+}
+interface ProbeHandlersResult {
+	matched: number;
+	written: number;
+	tables: string[];
+	firstEventKeys?: string[];
+}
+/**
+* Run handlers against pre-built sample payloads in memory (no Index, no
+* Postgres). Deploy uses this with print-schema dummy events to refuse
+* EMPTY_MAPPING before DDL apply.
+*/
+declare function probeHandlers(def: ProbeHandlersDef, samples: Array<{
+	source: string
+	event: Record<string, unknown>
+}>): Promise<ProbeHandlersResult>;
+export { toHandlerPayload, toContractCallPayload, runSubgraphTest, probeHandlers, createTestContext, buildEventPayload, buildEvent, TxMeta2 as TxMeta, TestSubgraphContext, SubgraphTestSource, SubgraphTestResult, RunSubgraphTestInput, ProbeHandlersResult, ProbeHandlersDef, IndexTestRow, IndexEventRow, IndexContractCallRow, EventTrace, BlockMeta };