@johannc-dev/zyrk 0.0.0-stage → 0.2.0

package/dist/sdk.js

@@ -0,0 +1,208 @@
+export const Side = { buy: 0, sell: 1, event: 2 };
+export const Protocol = { pumpfun: 0, pumpswap: 1 };
+export const OrderFlag = {
+    known: 1,
+    bySignature: 2,
+    ambiguous: 4,
+    amountDiffers: 8,
+    unknownNoMatch: 16,
+    unknownNotCovered: 32,
+    unknownNoKey: 64,
+    notFinalized: 128,
+};
+export const NO_TX_INDEX = 0xffff_ffff;
+export const NO_EVENT_INDEX = 0xffff;
+export const NO_TX_ID = 0xffff_ffff;
+export const TxFlag = {
+    bySignature: 1,
+    byChain: 2,
+    chainIndex: 4,
+    providerIndex: 8,
+    unknown: 16,
+};
+export const NO_ADDRESS = -1;
+export const HOUR_MS = 3_600_000;
+export const SOL_MINT = "So11111111111111111111111111111111111111112";
+export const MarketEvent = {
+    none: 0,
+    migrate: 1,
+    createPool: 2,
+    add: 3,
+    remove: 4,
+    create: 5,
+    feeHolders: 6,
+    feeShareholders: 7,
+    feeCreator: 8,
+    feeSocial: 9,
+    feeOther: 10,
+};
+export const MarketFlag = {
+    reserves: 1,
+    virtualReserves: 2,
+    multiOpRow: 4,
+    chainBreak: 8,
+    chainUnchecked: 16,
+    creatorInitialBuy: 32,
+    cashback: 64,
+    mayhem: 128,
+    feeWithoutToken: 256,
+    invertedPool: 512,
+};
+export function isFinal(result) {
+    return result.status !== "queued" && result.status !== "running";
+}
+export function txFlagNames(flags) {
+    return Object.keys(TxFlag).filter((k) => (flags & TxFlag[k]) !== 0);
+}
+export function sameTransaction(a, i, b, j) {
+    if (!a.tx || !b.tx)
+        throw new RangeError("sameTransaction needs batches read withTx: true");
+    const x = a.tx.id[i] ?? NO_TX_ID;
+    return a.hour === b.hour && x !== NO_TX_ID && x === b.tx.id[j];
+}
+export function deliveryNow(delivery) {
+    return delivery.replay?.clockMs ?? Date.now();
+}
+export function isDelivery(args) {
+    return isRecord(args) && args.kind === "events" && Array.isArray(args.events);
+}
+export function isCompletion(args) {
+    return (isRecord(args) &&
+        args.kind === "completion" &&
+        typeof args.executionId === "string");
+}
+export const SDK_MARKER = "__zyrkSdk";
+export const SDK_VERSION = "0.2";
+export function defineProgram(program) {
+    Object.defineProperty(program, SDK_MARKER, {
+        value: SDK_VERSION,
+        enumerable: false,
+    });
+    return program;
+}
+export function tradeId(batch, i) {
+    return `${batch.hour}:${batch.line[i]}:${batch.op[i]}`;
+}
+export function parseTradeId(id) {
+    const match = /^(\d+):(\d+):(\d+)$/.exec(id);
+    if (!match)
+        throw new RangeError(`Invalid trade id: ${id}`);
+    return {
+        hour: Number(match[1]),
+        line: Number(match[2]),
+        op: Number(match[3]),
+    };
+}
+export function compareTradeIds(a, b) {
+    const x = parseTradeId(a), y = parseTradeId(b);
+    return x.hour - y.hour || x.line - y.line || x.op - y.op;
+}
+export function operationTradeId(operation) {
+    const id = operation.id;
+    if (typeof id === "string" && /^\d+:\d+:\d+$/.test(id))
+        return id;
+    return operation.order?.ord ?? null;
+}
+export function priceFactor(percent) {
+    const ratio = percent >= 0 ? 1 + percent / 100 : 1 / (1 + percent / 100);
+    const factor = Math.floor(ratio * 10_000 + 1e-9) / 10_000;
+    if (!(factor >= 1.01 && factor <= 11)) {
+        throw new RangeError(`priceFactor: ${percent} % is outside 1.01..11`);
+    }
+    return factor;
+}
+export function addressAt(batch, index) {
+    return index < 0 ? null : (batch.addresses[index] ?? null);
+}
+export function addressIndex(batch, address) {
+    return batch.addresses.indexOf(address);
+}
+export function mintOf(batch, i) {
+    return addressAt(batch, batch.mint[i] ?? NO_ADDRESS) ?? "";
+}
+export function traderOf(batch, i) {
+    return addressAt(batch, batch.trader[i] ?? NO_ADDRESS);
+}
+export function poolOf(batch, i) {
+    return addressAt(batch, batch.pool[i] ?? NO_ADDRESS);
+}
+export function quoteMintOf(batch, i) {
+    return addressAt(batch, batch.quoteMint[i] ?? NO_ADDRESS) ?? "";
+}
+export function sideOf(batch, i) {
+    if (batch.side[i] === Side.event)
+        throw new RangeError(`Row ${i} is a pool event (withEvents), not a trade`);
+    return batch.side[i] === Side.sell ? "sell" : "buy";
+}
+export function protocolOf(batch, i) {
+    return batch.protocol[i] === Protocol.pumpswap ? "pumpswap" : "pumpfun";
+}
+export function compareChainOrder(a, i, b, j) {
+    const x = a.order, y = b.order;
+    if (!x || !y)
+        throw new RangeError("compareChainOrder needs batches read withOrder: true");
+    return ((a.slot[i] ?? 0) - (b.slot[j] ?? 0) ||
+        (x.txIndex[i] ?? NO_TX_INDEX) - (y.txIndex[j] ?? NO_TX_INDEX) ||
+        (x.eventIndex[i] ?? NO_EVENT_INDEX) - (y.eventIndex[j] ?? NO_EVENT_INDEX) ||
+        a.hour - b.hour ||
+        (a.line[i] ?? 0) - (b.line[j] ?? 0) ||
+        (a.op[i] ?? 0) - (b.op[j] ?? 0));
+}
+export function hourStartMs(hour) {
+    return hour * HOUR_MS;
+}
+const orNull = (value) => value === undefined || Number.isNaN(value) ? null : value;
+export function tradeAt(batch, i) {
+    if (!Number.isInteger(i) || i < 0 || i >= batch.length)
+        throw new RangeError(`Row ${i} out of range (length ${batch.length})`);
+    return {
+        id: tradeId(batch, i),
+        hour: batch.hour,
+        line: batch.line[i],
+        op: batch.op[i],
+        slot: batch.slot[i],
+        timeMs: batch.timeMs[i],
+        receivedMs: orNull(batch.receivedMs[i]),
+        side: sideOf(batch, i),
+        protocol: protocolOf(batch, i),
+        mint: mintOf(batch, i),
+        pool: poolOf(batch, i),
+        trader: traderOf(batch, i),
+        quoteMint: quoteMintOf(batch, i),
+        tokenRaw: batch.tokenRaw[i],
+        tokenDecimals: batch.tokenDecimals[i],
+        quoteRaw: batch.quoteRaw[i],
+        quoteDecimals: batch.quoteDecimals[i],
+        tokenAmount: batch.tokenAmount[i],
+        quoteAmount: batch.quoteAmount[i],
+        price: orNull(batch.price[i]),
+        priceSol: orNull(batch.priceSol[i]),
+        priceUsd: orNull(batch.priceUsd[i]),
+        quotePriceUsd: orNull(batch.quotePriceUsd[i]),
+        usdValue: orNull(batch.usdValue[i]),
+        signature: batch.signatures?.[i] ?? null,
+    };
+}
+export const STORAGE_STATUS_BY_CODE = {
+    blocked_type: 415,
+    forbidden: 403,
+    invalid_request: 400,
+    not_found: 404,
+    quota_exceeded: 413,
+    too_large: 413,
+    unavailable: 503,
+    already_exists: 409,
+    value_changed: 409,
+    io_limit: 429,
+    upload_limit: 429,
+    precondition_failed: 412,
+};
+export function isSdkError(error, code) {
+    if (!(error instanceof Error))
+        return false;
+    const actual = error.code;
+    return typeof actual === "string" && (code === undefined || actual === code);
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/dist/stream.d.ts

@@ -0,0 +1,36 @@
+import { Stream } from "effect";
+import { ExecutionEvent, Gap } from "./contracts.js";
+import { DecodeError, NetworkError } from "./errors.js";
+export { ExecutionEvent, Gap } from "./contracts.js";
+export type FunctionsMessage = {
+    readonly _tag: "Execution";
+    readonly event: ExecutionEvent;
+} | {
+    readonly _tag: "Gap";
+    readonly gap: Gap;
+};
+export type StreamError = DecodeError | NetworkError;
+export interface StreamOptions {
+    readonly url: string;
+    readonly apiKey: string;
+    /** Resume after this sequence number. */
+    readonly afterSeq?: number;
+}
+/**
+ * Live execution events of the account. Gaps are emitted as values; the
+ * stream fails on undecodable payloads or when the server refuses the join.
+ * The socket is closed when the stream is interrupted or ends.
+ */
+export declare const executionEvents: (options: StreamOptions) => Stream.Stream<FunctionsMessage, StreamError>;
+/** Callback API kept for existing users; errors are tagged `StreamError`s or raw socket errors. */
+export declare function subscribeFunctions(options: {
+    url: string;
+    apiKey: string;
+    afterSeq?: number;
+    onEvent: (event: ExecutionEvent) => void;
+    onGap?: (gap: Gap) => void;
+    onError?: (error: unknown) => void;
+}): {
+    close(): void;
+    readonly cursor: number | undefined;
+};

package/dist/stream.js

@@ -0,0 +1,69 @@
+import { Socket } from "phoenix";
+import { Cause, Effect, Queue, Result, Stream } from "effect";
+import { ExecutionEvent, Gap, decodeWith, } from "./contracts.js";
+import { DecodeError, NetworkError } from "./errors.js";
+export { ExecutionEvent, Gap } from "./contracts.js";
+const decoder = (schema, what) => decodeWith(schema, undefined, (message) => new DecodeError({ what, message }));
+const decodeEvent = decoder(ExecutionEvent, "execution event");
+const decodeGap = decoder(Gap, "stream gap");
+function connect(options, handlers) {
+    let cursor = options.afterSeq;
+    const endpoint = new URL("/v1/stream", options.url);
+    endpoint.protocol =
+        endpoint.protocol === "https:" || endpoint.protocol === "wss:"
+            ? "wss:"
+            : "ws:";
+    const socket = new Socket(endpoint.toString(), {
+        params: { api_key: options.apiKey },
+        transport: WebSocket,
+    });
+    const channel = socket.channel("functions", () => cursor === undefined ? {} : { after_seq: cursor });
+    channel.on("execution", (raw) => {
+        const result = decodeEvent(raw);
+        if (Result.isFailure(result))
+            return handlers.fail(result.failure);
+        const event = result.success;
+        if (cursor !== undefined && event.seq <= cursor)
+            return;
+        cursor = event.seq;
+        handlers.message({ _tag: "Execution", event });
+    });
+    channel.on("gap", (raw) => {
+        const result = decodeGap(raw);
+        if (Result.isFailure(result))
+            return handlers.fail(result.failure);
+        cursor = result.success.resumeAfter;
+        handlers.message({ _tag: "Gap", gap: result.success });
+    });
+    socket.onError((error) => handlers.transient(error));
+    channel.onError((error) => handlers.transient(error));
+    socket.connect();
+    channel.join().receive("error", (reason) => handlers.fail(new NetworkError({
+        url: endpoint.toString(),
+        message: `Stream join refused: ${JSON.stringify(reason)}`,
+        cause: reason,
+    })));
+    return {
+        close() {
+            channel.leave();
+            socket.disconnect();
+        },
+        get cursor() {
+            return cursor;
+        },
+    };
+}
+export const executionEvents = (options) => Stream.callback((queue) => Effect.acquireRelease(Effect.sync(() => connect(options, {
+    message: (message) => void Queue.offerUnsafe(queue, message),
+    fail: (error) => void Queue.failCauseUnsafe(queue, Cause.fail(error)),
+    transient: () => { },
+})), (connection) => Effect.sync(() => connection.close())));
+export function subscribeFunctions(options) {
+    return connect(options, {
+        message: (message) => message._tag === "Execution"
+            ? options.onEvent(message.event)
+            : options.onGap?.(message.gap),
+        fail: (error) => options.onError?.(error),
+        transient: (error) => options.onError?.(error),
+    });
+}

package/dist/webhook.d.ts

@@ -0,0 +1,43 @@
+/** What a webhook delivers (the JSON body). */
+export interface WebhookMessage {
+    /** Unique per message, the same on every delivery attempt: dedup on it. */
+    id: string;
+    /** Per account, 1, 2, 3… without holes; a hole is a message that failed for good. */
+    seq: number;
+    /** `send` (`ctx.webhook.send`), `execution.failed`, `execution.limit` or `test`. */
+    type: "send" | "execution.failed" | "execution.limit" | "test";
+    createdAt: number;
+    /** The payload of `ctx.webhook.send`, or `{ error }` for a failure. */
+    data: unknown;
+    /** Execution that produced it (absent for `test`). */
+    executionId?: string;
+    /** Attempt of that execution: a retried execution sends again with a higher one. */
+    attempt?: number;
+    /** Rank of the `send` call in that attempt (0, 1, …). */
+    index?: number;
+    program?: string;
+    function?: string;
+    workflow?: string;
+}
+export interface VerifyOptions {
+    /** Maximum age (and clock skew) of the signature, in seconds (default 300). */
+    toleranceSec?: number;
+    /** Current time in ms (tests). */
+    now?: number;
+}
+export declare class WebhookVerificationError extends Error {
+    readonly code: "missing_signature" | "malformed_signature" | "timestamp_out_of_tolerance" | "invalid_signature" | "invalid_body";
+    constructor(code: WebhookVerificationError["code"], message: string);
+}
+type HeaderBag = Headers | Record<string, string | string[] | undefined> | Map<string, string>;
+/**
+ * Checks `x-zyrk-signature` (`t=<unix>,v1=<hex>[,v1=<hex>]`, HMAC-SHA256 of
+ * `t + "." + body` with your secret) and returns the parsed message. Pass
+ * the **raw** body, exactly as received. During a secret rotation the
+ * header carries one `v1` per valid secret: either of your secrets passes.
+ * Pass an array to accept several secrets on your side too.
+ *
+ * Throws {@link WebhookVerificationError}.
+ */
+export declare const verifyWebhook: (secret: string | readonly string[], headers: HeaderBag, body: string | Uint8Array, options?: VerifyOptions) => WebhookMessage;
+export {};

package/dist/webhook.js

@@ -0,0 +1,54 @@
+import { createHmac, timingSafeEqual } from "node:crypto";
+export class WebhookVerificationError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = "WebhookVerificationError";
+        this.code = code;
+    }
+}
+const header = (headers, name) => {
+    if (typeof headers.get === "function") {
+        const v = headers.get(name);
+        return v ?? undefined;
+    }
+    const record = headers;
+    const key = Object.keys(record).find((k) => k.toLowerCase() === name);
+    const v = key === undefined ? undefined : record[key];
+    return Array.isArray(v) ? v[0] : v;
+};
+export const verifyWebhook = (secret, headers, body, options = {}) => {
+    const text = typeof body === "string" ? body : new TextDecoder().decode(body);
+    const raw = header(headers, "x-zyrk-signature");
+    if (!raw)
+        throw new WebhookVerificationError("missing_signature", "No x-zyrk-signature header");
+    let timestamp;
+    const signatures = [];
+    for (const part of raw.split(",")) {
+        const [k, v] = part.trim().split("=", 2);
+        if (k === "t" && v !== undefined && /^\d+$/.test(v))
+            timestamp = Number(v);
+        else if (k === "v1" && v !== undefined && /^[0-9a-f]{64}$/.test(v))
+            signatures.push(v);
+    }
+    if (timestamp === undefined || signatures.length === 0)
+        throw new WebhookVerificationError("malformed_signature", "Expected t=<unix>,v1=<hex>");
+    const tolerance = options.toleranceSec ?? 300;
+    const now = Math.floor((options.now ?? Date.now()) / 1000);
+    if (Math.abs(now - timestamp) > tolerance)
+        throw new WebhookVerificationError("timestamp_out_of_tolerance", `Signature timestamp is more than ${tolerance} s away from now`);
+    const secrets = typeof secret === "string" ? [secret] : secret;
+    const signed = `${timestamp}.${text}`;
+    const ok = secrets.some((s) => {
+        const expected = createHmac("sha256", s).update(signed).digest();
+        return signatures.some((candidate) => timingSafeEqual(expected, Buffer.from(candidate, "hex")));
+    });
+    if (!ok)
+        throw new WebhookVerificationError("invalid_signature", "No signature matches the secret");
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        throw new WebhookVerificationError("invalid_body", "Body is not JSON");
+    }
+};

package/package.json

@@ -1,6 +1,58 @@
 {
   "name": "@johannc-dev/zyrk",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "SDK and CLI for Zyrk hosted functions (funrun v2)",
+  "license": "UNLICENSED",
+  "publishConfig": {
+    "access": "public",
+    "provenance": false
+  },
+  "type": "module",
+  "types": "./dist/sdk.d.ts",
+  "files": [
+    "dist/*.js",
+    "dist/*.d.ts",
+    "README.md"
+  ],
+  "exports": {
+    ".": "./dist/sdk.js",
+    "./client": "./dist/client.js",
+    "./stream": "./dist/stream.js",
+    "./contracts": "./dist/contracts.js",
+    "./errors": "./dist/errors.js",
+    "./build": "./dist/build.js",
+    "./limits": "./dist/limits.js",
+    "./local": "./dist/local.js",
+    "./export": "./dist/export.js",
+    "./hourfile": "./dist/hourfile.js",
+    "./webhook": "./dist/webhook.js",
+    "./globals": {
+      "types": "./dist/globals.d.ts"
+    }
+  },
+  "bin": {
+    "zyrk": "./dist/cli.js"
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "scripts": {
+    "build": "node scripts/build.mjs",
+    "typecheck": "tsc --noEmit && tsc --noEmit -p tsconfig.test.json",
+    "test": "npm run build && npm run typecheck && node --test test/*.test.ts",
+    "format": "prettier --write src types scripts test examples package.json tsconfig.json tsconfig.test.json README.md",
+    "format:check": "prettier --check src types scripts test examples package.json tsconfig.json tsconfig.test.json README.md",
+    "prepack": "npm run build"
+  },
+  "dependencies": {
+    "effect": "4.1.2",
+    "esbuild": "0.28.2",
+    "phoenix": "1.7.24",
+    "typescript": "5.9.2"
+  },
+  "devDependencies": {
+    "@types/node": "24.10.0",
+    "@types/phoenix": "1.6.8",
+    "prettier": "3.6.2"
+  }
+}