@secondlayer/subgraphs 4.1.5 → 4.2.1

package/dist/src/runtime/catchup.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",
@@ -203,6 +208,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;
 }
@@ -233,29 +241,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 */