@inodra/sui 0.1.0

package/dist/webhooks.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Verification for Inodra webhook signatures.
+ *
+ * Inodra signs webhook deliveries with HMAC-SHA256 when the webhook has a
+ * secret configured. The signature arrives in the `X-Inodra-Signature`
+ * header as `t=<unix-seconds>,v1=<hex-hmac>` where the HMAC is computed
+ * over `<timestamp>.<raw-body>`.
+ */
+interface VerifyWebhookSignatureOptions {
+    /** Raw request body, exactly as received (before any JSON parsing). */
+    payload: string;
+    /** Value of the X-Inodra-Signature header. */
+    signature: string;
+    /** The webhook's secret. */
+    secret: string;
+    /** Max allowed age of the signature. Defaults to 300 seconds. */
+    toleranceSeconds?: number;
+    /** Current unix time in seconds (for testing). */
+    now?: number;
+}
+/**
+ * Verify a webhook delivery. Returns false for malformed, mismatched, or
+ * expired signatures — never throws on bad input.
+ *
+ * ```ts
+ * const valid = await verifyWebhookSignature({
+ *   payload: rawBody,
+ *   signature: req.headers["x-inodra-signature"],
+ *   secret: process.env.INODRA_WEBHOOK_SECRET,
+ * });
+ * ```
+ */
+declare function verifyWebhookSignature(options: VerifyWebhookSignatureOptions): Promise<boolean>;
+
+export { type VerifyWebhookSignatureOptions, verifyWebhookSignature };

package/dist/webhooks.js

@@ -0,0 +1,7 @@
+import {
+  verifyWebhookSignature
+} from "./chunk-4HKKW5QN.js";
+export {
+  verifyWebhookSignature
+};
+//# sourceMappingURL=webhooks.js.map

package/dist/webhooks.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/llms.txt

@@ -0,0 +1,189 @@
+# @inodra/sui — TypeScript SDK for the Inodra Sui platform
+
+> Complete, copy-paste-accurate reference for LLMs and coding agents.
+> Humans: prefer README.md. Everything below is verified against the live API.
+
+## Install
+
+npm install @inodra/sui
+# for grpc/graphql namespaces (wrapped from the official Sui SDK):
+npm install @mysten/sui @protobuf-ts/grpcweb-transport
+# only for native HTTP/2 gRPC on Node (@inodra/sui/node):
+npm install @protobuf-ts/grpc-transport @grpc/grpc-js
+
+Lean zero-dependency subpaths (no @mysten/sui needed): @inodra/sui/warp,
+@inodra/sui/manage, @inodra/sui/webhooks, @inodra/sui/events (needs only zod,
+installed automatically).
+
+## Client construction
+
+import { Inodra } from "@inodra/sui";            // universal (browser/edge/Node)
+import { Inodra } from "@inodra/sui/node";       // Node: native HTTP/2 gRPC
+
+const inodra = new Inodra({
+  network: "mainnet",                            // "mainnet" | "testnet" (default mainnet)
+  auth: { apiKey: process.env.INODRA_API_KEY },  // or auth: "<key>" shorthand
+  // auth: { sessionToken },                     // Authorization: Bearer
+  // auth: { getCredentials: async () => ({ headers: {...} }) },  // custom provider
+  // endpoints: { rest, graphql, grpc, grpcWeb, warpWs },         // local-dev overrides
+  // timeoutMs: 30000, maxRetries: 2, fetch, onResponseMeta,
+});
+
+Facts:
+- API keys look like indr_pat_... and are sent as x-api-key (or Bearer).
+- Retry policy: GET/PUT/DELETE retry on 429+5xx; POST/PATCH retry ONLY on 429
+  unless the per-request option { idempotent: true } is passed.
+- inodra.lastResponseMeta = { rateLimit: {limit, remaining, reset, throttled},
+  credits: {remaining, limit, replenishDate, degraded}, requestId } from the
+  most recent REST response.
+- Errors: InodraError (has .status, .code, .requestId, .body),
+  InodraAuthenticationError (401/403), InodraRateLimitError (429, has
+  .retryAfterSeconds), InodraTimeoutError, InodraWebhookSignatureError.
+- Data endpoints are mainnet-only (403 on testnet keys).
+
+## Namespaces (all lazy)
+
+inodra.grpc      → SuiGrpcClient from @mysten/sui over Inodra's gateway.
+                   Methods: getObject, getObjects, getTransaction (pass
+                   include: {effects: true} for useful output), getBalance,
+                   listBalances, listCoins, listOwnedObjects, listDynamicFields,
+                   getDynamicField, getCoinMetadata, getMoveFunction,
+                   getReferenceGasPrice, executeTransaction,
+                   signAndExecuteTransaction, simulateTransaction,
+                   waitForTransaction, verifyZkLoginSignature, plus .core.*
+                   (e.g. core.getBalance({owner, coinType})).
+                   NOTE: no checkpoint read methods on this client.
+inodra.graphql   → SuiGraphQLClient from @mysten/sui.
+                   await inodra.graphql.query({ query, variables })
+inodra.warp      → Warp real-time streams (see below)
+inodra.webhooks  → webhook CRUD + receiver verification (see below)
+inodra.data      → indexer REST (see below)
+inodra.catalog   → protocols() / events({network?, protocol?, category?, q?, includeUnverified?})
+inodra.account   → me() (key/org/project/network/tier), usage() (CU + latency stats)
+
+REST responses that create/read a resource are wrapped: { data: {...} } — e.g.
+(await inodra.warp.createEventStream({eventType})).data.id.
+
+## Warp real-time streams
+
+CRUD (subscription types: event, address, coin, object):
+  warp.createEventStream({ eventType, sender?, eventFieldFilters? })  // max 10 filters
+    eventFieldFilters: [{ field, moveType, operator: "eq"|"neq"|"gt"|"gte"|"lt"|"lte"|"contains", value }]
+  warp.createAddressStream({ address })
+  warp.createCoinStream({ address, coinType })
+  warp.createObjectStream({ objectId })
+  warp.list() / get(id) / update(id, {active}) / delete(id)
+
+Connect (one live connection per subscription):
+  const stream = inodra.warp.connect(subId, { mode?: "live"|"resume", lastEventId? });      // SSE, at-least-once
+  const stream = inodra.warp.connectWebSocket(subId, { autoAck?: boolean });                // WS, exactly-once via acks
+  stream.on("message", (e) => ...);   // e = { type, id, data }; e.data = { activityType,
+                                      //   txDigest, eventSequence, checkpoint, timestamp,
+                                      //   type: <Move event type>, sender, data: <decoded payload> }
+  stream.on("connected"|"error"|"reconnecting"|"quota_exceeded"|"close", ...)
+  for await (const e of stream) {...} // ends on close(); breaking the loop closes the stream
+  stream.close(); stream.ack(id);     // ack only needed with autoAck: false
+
+One-call typed stream (recommended):
+  const swaps = await inodra.warp.streamCatalogEvent("cetus.swap", {
+    ephemeral: true,          // delete the subscription when the stream closes
+    transport: "sse"|"ws",    // default sse
+    sender?, eventFieldFilters?,
+  });
+  for await (const { payload, envelope } of swaps) { ... }  // payload is typed + validated
+
+Semantics: first connect is LIVE (backlog dropped) unless mode:"resume" or
+lastEventId is given. Reconnects always resume from the last delivered id.
+Resume replay is at-least-once, NOT exact-cursor: expect duplicates around the
+cursor's checkpoint and out-of-order interleaving after reconnects — dedupe by
+event id (format "<checkpoint>_<txIdx>_<evtIdx>") if you need idempotency.
+Billing: ~12 CU/min connection time + 2 credits per delivered event.
+
+## Typed catalog events (@inodra/sui/events)
+
+import { catalogEvents, parseCatalogEvent, matchCatalogEvent, resolveCatalogEvent } from "@inodra/sui/events";
+
+- catalogEvents: map keyed by id → { id, protocolId, label, category, description,
+  generic, schema (zod), deployments: [{network, eventType, primary?}] }.
+- matchCatalogEvent(msg, id) → wire-typed payload | undefined (no validation).
+- parseCatalogEvent(msg, id) → validated+normalized payload | undefined; THROWS
+  if the event matches but fails its schema. Normalization: u64/u128/u256 →
+  decimal string, TypeName → string, Option<T> → T|null, Balance<T> → value string.
+- Both accept a Warp stream message, a bare event payload, or a parsed webhook body.
+- resolveCatalogEvent(rawMoveEventType, {network?}) → catalog entry | undefined.
+- Schemas are loose: unknown fields pass through (protocol upgrades don't break you).
+
+All 121 catalog event ids:
+7k.confirm-swap, 7k.swap, aftermath.deposit, aftermath.perp-funding, aftermath.perp-liquidated, aftermath.swap, alphafi.liquidity-change, alphafi.reward, bluefin.fee-collected, bluefin.liquidity-provided, bluefin.liquidity-removed, bluefin.pool-created, bluefin.position-closed, bluefin.position-opened, bluefin.reward-collected, bluefin.swap, bucket.borrow, bucket.deposit-collateral, bucket.position-updated, bucket.redeem, bucket.repay, bucket.sbuck-deposit, bucket.sbuck-rewards, bucket.withdraw-collateral, cetus.add-liquidity, cetus.close-position, cetus.collect-fee, cetus.create-pool, cetus.open-position, cetus.remove-liquidity, cetus.swap, current.borrow, current.deposit, current.liquidate, current.repay, current.withdraw, deepbook.balance, deepbook.flash-loan, deepbook.order-canceled, deepbook.order-filled, deepbook.order-info, deepbook.order-placed, ember.deposit, ember.rate-updated, ember.redeem-processed, ember.redeem-request, flowx.amm-pair-created, flowx.amm-swap, flowx.clmm-pool-created, flowx.clmm-swap, haedal.instant-unstaked, haedal.staked, haedal.unstaked, kai.add-liquidity, kai.deleverage, kai.liquidation, kai.position-open, kai.reduce, kai.supply, kai.supply-withdraw, kriya.add-liquidity, kriya.swap, magma.add-liquidity, magma.collect-fee, magma.collect-reward, magma.create-pool, magma.remove-liquidity, magma.swap, mole.add-debt, mole.deposit, mole.harvest, mole.kill, mole.withdraw, mole.work, momentum.add-liquidity, momentum.collect-fee, momentum.collect-reward, momentum.pool-created, momentum.remove-liquidity, momentum.repay-flash-swap, momentum.swap, navi.borrow, navi.deposit, navi.liquidation, navi.repay, navi.withdraw, pyth.price-feed-update, scallop.borrow, scallop.collateral-deposit, scallop.collateral-withdraw, scallop.liquidation, scallop.repay, springsui.epoch-changed, springsui.stake, springsui.unstake, steamm.bank-deposit, steamm.bank-withdraw, suilend.borrow, suilend.claim-reward, suilend.deposit, suilend.liquidate, suilend.repay, suilend.withdraw, supra.price-update, turbos.add-liquidity, turbos.pool-created, turbos.remove-liquidity, turbos.swap, typus.dov-auction, typus.dov-bid, typus.dov-settle, typus.perp-funding, typus.perp-liquidate, typus.perp-lp-burn, typus.perp-lp-mint, typus.perp-order, volo.staked, volo.unstaked, walrus.blob-certified, walrus.blob-deleted, walrus.blob-registered
+
+## Arbitrary (uncataloged) event types — reflection + codegen
+
+Runtime (schema built from on-chain struct layout, cached per type):
+  const schema = await inodra.events.schemaFor("0xpkg::vault::Deposit<0x2::sui::SUI>");
+  const payload = await inodra.events.parseEvent(msg, "0xpkg::vault::Deposit");
+  // parseEvent: base type (no <...>) matches every instantiation, each typed
+  // concretely; returns undefined for other events; throws on schema mismatch.
+Standalone (no facade): new EventSchemaReflector({apiKey?, network?, url?}) from
+@inodra/sui/events — url may be a public Sui GraphQL endpoint (keyless).
+Encoding rules identical to catalog schemas (u64→string, TypeName→string,
+Option→null, Balance→value string, nested structs recursed, loose objects;
+cycles/depth>6 fall back to unknown).
+
+Build-time static types (CLI, ships with the package):
+  INODRA_API_KEY=... npx inodra-sui codegen-events "<type...>" -o out.gen.ts \
+    [--network mainnet|testnet] [--url <graphql>] [--import-from <spec>]
+  # without INODRA_API_KEY it uses the public Sui GraphQL for the network
+Emitted file: zod schemas + z.infer types per event + reflectedEventSchemas map
+keyed by canonical type; imports only zod and @inodra/sui/events.
+
+## Webhooks
+
+Create (same 4 types as Warp; all take webhookUrl):
+  webhooks.createEvent({ eventType, webhookUrl, sender?, eventFieldFilters? })
+  webhooks.createAddress({ address, webhookUrl })
+  webhooks.createCoin({ address, coinType, webhookUrl })
+  webhooks.createObject({ objectId, webhookUrl })
+  webhooks.list() / get(id) / update(id, {...}) / delete(id)
+Create response .data includes webhookSecret — store it for verification.
+
+Receiver (use the EXACT raw body string, before any JSON.parse):
+  const body = await inodra.webhooks.constructEvent({
+    payload: rawBody,
+    signature: req.headers["x-inodra-signature"],   // format t=<unix>,v1=<hmac-sha256-hex>
+    secret: webhookSecret,
+  }); // throws InodraWebhookSignatureError on bad/expired signature (300s tolerance)
+  // body = { payloadVersion: 1, payload: { webhookId, activityType, txDigest,
+  //          eventSequence, checkpoint, timestamp, type, sender, data } }
+  const swap = parseCatalogEvent(body, "cetus.swap");   // typed narrowing
+Standalone: verifyWebhookSignature({payload, signature, secret, toleranceSeconds?}) → boolean.
+
+## Data API (mainnet only)
+
+inodra.data.accounts: get(addr), balance(addr), delegations(addr),
+  objects(addr, {limit?, cursor?}), iterateObjects(addr) → AsyncGenerator,
+  transactions(addr, {limit?, cursor?, format?: "raw"|"activity", includeReceived?}),
+  iterateTransactions(addr) → AsyncGenerator
+inodra.data.coins: get(coinType) [denomination], metadata(coinType) [name/symbol/links]
+inodra.data.objects: metadata({ objectId }) [SINGULAR], transactions(objectId, {limit?, cursor?}),
+  iterateTransactions(objectId)
+inodra.data.packages: get(packageId)
+inodra.data.chain: info(), staking(), stats()
+inodra.data.validators: list(), apy(), commission(), get(validatorAddress)
+inodra.data.suins: resolve(name), reverse(address) [404 if no name],
+  resolveBatch({names}), availability(name)
+Paginated responses: { data: [...], pagination: { limit, cursor?, hasNext } }.
+List query params limit/cursor are STRINGS (e.g. { limit: "50" }).
+
+## Endpoints
+
+mainnet: https://mainnet-api.inodra.com/v1 (REST/GraphQL/SSE),
+  mainnet-grpc.inodra.com:443 (gRPC), wss://mainnet-api.inodra.com/v1 (WS)
+testnet: same shape with testnet- prefix.
+Public OpenAPI spec: https://api.inodra.com/openapi.json
+
+## Regeneration (maintainers)
+
+bun run generate         # OpenAPI types + event schemas from the live API
+bun run verify:events    # validate every generated schema vs live chain events
+bun run e2e              # extensive live e2e (INODRA_API_KEY required)
+node scripts/webhook-live.mjs  # real inbound webhook delivery via tunnel

package/package.json

@@ -0,0 +1,119 @@
+{
+	"name": "@inodra/sui",
+	"version": "0.1.0",
+	"description": "TypeScript SDK for the Inodra Sui platform — gRPC, GraphQL, Warp real-time streams, webhooks, typed protocol events",
+	"license": "Apache-2.0",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/inodrahq/sdk-ts.git"
+	},
+	"homepage": "https://inodra.com",
+	"bugs": {
+		"url": "https://github.com/inodrahq/sdk-ts/issues"
+	},
+	"keywords": ["sui", "blockchain", "sdk", "inodra", "grpc", "graphql", "webhooks", "streaming", "web3"],
+	"type": "module",
+	"main": "./dist/index.cjs",
+	"module": "./dist/index.js",
+	"types": "./dist/index.d.ts",
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"import": "./dist/index.js",
+			"require": "./dist/index.cjs"
+		},
+		"./node": {
+			"types": "./dist/node.d.ts",
+			"import": "./dist/node.js",
+			"require": "./dist/node.cjs"
+		},
+		"./grpc": {
+			"types": "./dist/grpc.d.ts",
+			"import": "./dist/grpc.js",
+			"require": "./dist/grpc.cjs"
+		},
+		"./grpc-web": {
+			"types": "./dist/grpc-web.d.ts",
+			"import": "./dist/grpc-web.js",
+			"require": "./dist/grpc-web.cjs"
+		},
+		"./graphql": {
+			"types": "./dist/graphql.d.ts",
+			"import": "./dist/graphql.js",
+			"require": "./dist/graphql.cjs"
+		},
+		"./events": {
+			"types": "./dist/events.d.ts",
+			"import": "./dist/events.js",
+			"require": "./dist/events.cjs"
+		},
+		"./warp": {
+			"types": "./dist/warp.d.ts",
+			"import": "./dist/warp.js",
+			"require": "./dist/warp.cjs"
+		},
+		"./manage": {
+			"types": "./dist/manage.d.ts",
+			"import": "./dist/manage.js",
+			"require": "./dist/manage.cjs"
+		},
+		"./webhooks": {
+			"types": "./dist/webhooks.d.ts",
+			"import": "./dist/webhooks.js",
+			"require": "./dist/webhooks.cjs"
+		}
+	},
+	"bin": {
+		"inodra-sui": "bin/inodra-sui.mjs"
+	},
+	"files": ["dist", "bin", "llms.txt"],
+	"sideEffects": false,
+	"scripts": {
+		"build": "tsup",
+		"check-types": "tsc --noEmit",
+		"generate": "bun run generate:api && bun run generate:events",
+		"generate:api": "openapi-typescript \"${INODRA_SPEC_URL:-https://api.inodra.com/openapi.json}\" -o src/generated/api.ts",
+		"generate:events": "bun scripts/generate-events.ts",
+		"verify:events": "bun scripts/verify-events.ts",
+		"test": "vitest",
+		"test:run": "vitest run",
+		"e2e": "node scripts/e2e.mjs",
+		"smoke": "node examples/smoke.mjs"
+	},
+	"engines": {
+		"node": ">=18"
+	},
+	"peerDependencies": {
+		"@grpc/grpc-js": "^1.13.0",
+		"@mysten/sui": "^2.0.0",
+		"@protobuf-ts/grpc-transport": "^2.11.0",
+		"@protobuf-ts/grpcweb-transport": "^2.11.0"
+	},
+	"peerDependenciesMeta": {
+		"@grpc/grpc-js": {
+			"optional": true
+		},
+		"@mysten/sui": {
+			"optional": true
+		},
+		"@protobuf-ts/grpc-transport": {
+			"optional": true
+		},
+		"@protobuf-ts/grpcweb-transport": {
+			"optional": true
+		}
+	},
+	"devDependencies": {
+		"@grpc/grpc-js": "^1.14.4",
+		"@mysten/sui": "^2.17.0",
+		"@protobuf-ts/grpc-transport": "^2.11.1",
+		"@protobuf-ts/grpcweb-transport": "^2.11.1",
+		"openapi-typescript": "^7.6.0",
+		"tsup": "^8.3.0",
+		"typescript": "^5.8.2",
+		"vitest": "^3.2.4"
+	},
+	"dependencies": {
+		"zod": "^4.4.3"
+	}
+}