tapimo 0.0.0 → 0.0.2

package/dist/internal/Response.d.ts

@@ -0,0 +1,132 @@
+import type { Context } from 'hono';
+import type * as z from 'zod/mini';
+/** Creates a JSON error response. */
+export declare function error<const status extends error.Status, const code extends string>(c: Context, options: error.Options<status, code>): Response & import("hono").TypedResponse<{
+    error: string | code | readonly error.Detail[] | undefined extends bigint | readonly bigint[] ? never : { [K in keyof {
+        code: code;
+        details?: readonly error.Detail[] | undefined;
+        message: string;
+    } as ({
+        /** Stable machine-readable error code. */
+        code: code;
+        /** Detailed validation or upstream error information. */
+        details?: readonly error.Detail[] | undefined;
+        /** Human-readable error message. */
+        message: string;
+    }[K] extends infer T ? T extends {
+        /** Stable machine-readable error code. */
+        code: code;
+        /** Detailed validation or upstream error information. */
+        details?: readonly error.Detail[] | undefined;
+        /** Human-readable error message. */
+        message: string;
+    }[K] ? T extends import("hono/utils/types").InvalidJSONValue ? true : false : never : never) extends true ? never : K]: boolean extends ({
+        /** Stable machine-readable error code. */
+        code: code;
+        /** Detailed validation or upstream error information. */
+        details?: readonly error.Detail[] | undefined;
+        /** Human-readable error message. */
+        message: string;
+    }[K] extends infer T ? T extends {
+        /** Stable machine-readable error code. */
+        code: code;
+        /** Detailed validation or upstream error information. */
+        details?: readonly error.Detail[] | undefined;
+        /** Human-readable error message. */
+        message: string;
+    }[K] ? T extends import("hono/utils/types").InvalidJSONValue ? true : false : never : never) ? import("hono/utils/types").JSONParsed<{
+        /** Stable machine-readable error code. */
+        code: code;
+        /** Detailed validation or upstream error information. */
+        details?: readonly error.Detail[] | undefined;
+        /** Human-readable error message. */
+        message: string;
+    }[K], bigint | readonly bigint[]> | undefined : import("hono/utils/types").JSONParsed<{
+        /** Stable machine-readable error code. */
+        code: code;
+        /** Detailed validation or upstream error information. */
+        details?: readonly error.Detail[] | undefined;
+        /** Human-readable error message. */
+        message: string;
+    }[K], bigint | readonly bigint[]>; };
+    requestId: string;
+}, status, "json">;
+/**
+ * Rejects a well-formed but unsupported chain id with a clear 400, listing the
+ * chain ids this deployment serves. Used to short-circuit before an unknown
+ * chain reaches an upstream (which would surface as an opaque `upstream_error`).
+ */
+export declare function unsupportedChainId(c: Context, chainId: number, supported: Iterable<number>): Response & import("hono").TypedResponse<{
+    error: {
+        code: "chain_id_unsupported";
+        details?: readonly error.Detail[] | undefined;
+        message: string;
+    };
+    requestId: string;
+}, 400, "json">;
+/**
+ * Maps an unexpected upstream failure to a 502 JSON error envelope. Rethrows
+ * non-`Error` causes so the global handler can convert them.
+ */
+export declare function upstream(c: Context, cause: unknown): Response & import("hono").TypedResponse<{
+    error: {
+        code: "upstream_error";
+        details?: readonly error.Detail[] | undefined;
+        message: string;
+    };
+    requestId: string;
+}, 502, "json">;
+/**
+ * Validates `value` against `schema`. Returns the parsed value on success or
+ * throws a generic upstream error so the public response body never leaks Zod
+ * internals.
+ */
+export declare function validated<schema extends z.ZodMiniType>(schema: schema, value: unknown): z.output<schema>;
+/** Converts standard validation issues into API error details. */
+export declare function validationDetails(issues: readonly validationDetails.Issue[]): error.Detail[];
+export declare namespace error {
+    /** Public API error response body. */
+    type Body<code extends string = string> = {
+        /** Public error envelope. */
+        error: {
+            /** Stable machine-readable error code. */
+            code: code;
+            /** Detailed validation or upstream error information. */
+            details?: readonly Detail[] | undefined;
+            /** Human-readable error message. */
+            message: string;
+        };
+        /** Request id for support/debugging. */
+        requestId: string;
+    };
+    /** One public API error detail. */
+    type Detail = {
+        /** Human-readable detail message. */
+        message: string;
+        /** Path to the invalid value. */
+        path?: readonly (number | string)[] | undefined;
+    };
+    /** HTTP status code accepted by the public error helper. */
+    type Status = 400 | 401 | 403 | 404 | 409 | 412 | 413 | 415 | 429 | 500 | 502 | 503;
+    /** Options for creating a JSON error response. */
+    type Options<status extends Status = Status, code extends string = string> = {
+        /** Stable machine-readable error code. */
+        code: code;
+        /** Detailed validation or upstream error information. */
+        details?: readonly Detail[] | undefined;
+        /** Human-readable error message. */
+        message: string;
+        /** HTTP status code. */
+        status: status;
+    };
+}
+export declare namespace validationDetails {
+    /** Standard-schema validation issue shape used by Hono validators. */
+    type Issue = {
+        /** Human-readable validation message. */
+        message: string;
+        /** Path to the invalid value. */
+        path?: readonly unknown[] | undefined;
+    };
+}
+//# sourceMappingURL=Response.d.ts.map

package/dist/internal/Response.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Response.d.ts","sourceRoot":"","sources":["../../src/internal/Response.ts"],"names":[],"mappings":"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"}

package/dist/internal/Response.js

@@ -0,0 +1,72 @@
+/** Creates a JSON error response. */
+export function error(c, options) {
+    const { code, details, message, status } = options;
+    // Error envelopes embed `requestId` and other per-request state, so they
+    // must never be cached by clients, proxies, or CDNs.
+    c.header('Cache-Control', 'no-store');
+    // Record the stable code so the canonical request log line (`Log.middleware`)
+    // can include it without re-parsing the response body.
+    c.set('errorCode', code);
+    const body = {
+        error: {
+            code,
+            ...(details === undefined ? {} : { details }),
+            message,
+        },
+        requestId: c.get('requestId'),
+    };
+    return c.json(body, status);
+}
+/**
+ * Rejects a well-formed but unsupported chain id with a clear 400, listing the
+ * chain ids this deployment serves. Used to short-circuit before an unknown
+ * chain reaches an upstream (which would surface as an opaque `upstream_error`).
+ */
+export function unsupportedChainId(c, chainId, supported) {
+    const ids = [...supported].sort((a, b) => a - b).join(', ');
+    return error(c, {
+        code: 'chain_id_unsupported',
+        message: `Unsupported chain id: ${chainId}. Supported chain ids: ${ids}.`,
+        status: 400,
+    });
+}
+/**
+ * Maps an unexpected upstream failure to a 502 JSON error envelope. Rethrows
+ * non-`Error` causes so the global handler can convert them.
+ */
+export function upstream(c, cause) {
+    if (cause instanceof Error)
+        return error(c, { code: 'upstream_error', message: cause.message, status: 502 });
+    throw cause;
+}
+/**
+ * Validates `value` against `schema`. Returns the parsed value on success or
+ * throws a generic upstream error so the public response body never leaks Zod
+ * internals.
+ */
+export function validated(schema, value) {
+    const result = schema.safeParse(value);
+    if (result.success)
+        return result.data;
+    throw new Error('Upstream returned invalid response data');
+}
+/** Converts standard validation issues into API error details. */
+export function validationDetails(issues) {
+    return issues.map((issue) => {
+        const path = issue.path?.map(pathSegment).filter((segment) => segment !== undefined);
+        if (!path?.length)
+            return { message: issue.message };
+        return { message: issue.message, path };
+    });
+}
+function pathSegment(segment) {
+    if (typeof segment === 'string' || typeof segment === 'number')
+        return segment;
+    if (!segment || typeof segment !== 'object' || !('key' in segment))
+        return undefined;
+    const { key } = segment;
+    if (typeof key === 'string' || typeof key === 'number')
+        return key;
+    return undefined;
+}
+//# sourceMappingURL=Response.js.map

package/dist/internal/Response.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Response.js","sourceRoot":"","sources":["../../src/internal/Response.ts"],"names":[],"mappings":"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"}

package/dist/internal/Schema.d.ts

@@ -0,0 +1,257 @@
+import { Hex as core_Hex } from 'ox';
+import * as z from 'zod/mini';
+/**
+ * Attaches an OpenAPI description to an object/array schema that is later
+ * derived from via `z.partial`/`z.extend`. `zod/mini` exposes descriptions only
+ * through `.check(z.describe(...))`, but that adds a refinement which those
+ * derivations reject. Cloning and registering the description directly (as
+ * classic zod's `.describe()` does) keeps the schema refinement-free. Plain
+ * fields use `.check(z.describe(...))` directly.
+ */
+export declare function describe<const schema extends z.ZodMiniType>(schema: schema, description: string): schema;
+/** Lowercase 0x-prefixed 20-byte account address. */
+export declare const Address: z.ZodMiniPipe<z.ZodMiniTemplateLiteral<`0x${string}`>, z.ZodMiniTransform<`0x${string}`, `0x${string}`>>;
+/**
+ * Lowercase 0x-prefixed 20-byte TIP-20 token contract address. The OpenAPI
+ * example must be attached to the inner pre-transform schema (path/query
+ * params read examples from the pipe input), so callers that need a different
+ * example per field build a fresh `TokenAddress` via `tokenAddress(example)`
+ * instead of overriding via an outer `.check(z.meta(...))`.
+ */
+export declare const TokenAddress: z.ZodMiniPipe<z.ZodMiniTemplateLiteral<`0x${string}`>, z.ZodMiniTransform<`0x${string}`, `0x${string}`>>;
+/**
+ * Builds a `TokenAddress`-shaped schema with the given OpenAPI example. Use
+ * when a path/query param wants a different example than the shared
+ * `TokenAddress` default (e.g. the two sides of a trading pair).
+ *
+ * The example must be a TIP-20 token address (`0x20c` prefix); a non-TIP-20
+ * example in the docs would be misleading because the route validates the
+ * value as a TIP-20 token contract at runtime.
+ */
+export declare function tokenAddress(example: core_Hex.Hex): z.ZodMiniPipe<z.ZodMiniTemplateLiteral<`0x${string}`>, z.ZodMiniTransform<`0x${string}`, `0x${string}`>>;
+/** Maps human-readable chain aliases to their Tempo chain id. */
+export declare const chainIdAlias: {
+    readonly mainnet: 4217;
+    readonly testnet: 42431;
+};
+/**
+ * Tempo chain id. Accepts a chain alias (`mainnet`/`testnet`) or any positive
+ * integer chain id (a number or numeric string), normalizing all forms to a
+ * numeric chain id. Arbitrary ids are allowed so a self-hosted deployment can
+ * serve a localnet (e.g. `31337`); the deployment must configure an `rpc`/`tidx`
+ * upstream for any chain beyond the built-in public defaults.
+ */
+export declare const ChainId: z.ZodMiniPipe<z.ZodMiniUnion<readonly [z.ZodMiniPipe<z.ZodMiniEnum<{
+    mainnet: "mainnet";
+    testnet: "testnet";
+}>, z.ZodMiniTransform<4217 | 42431, "mainnet" | "testnet">>, z.ZodMiniNumber<unknown>]>, z.ZodMiniNumber<number>>;
+/**
+ * Optional `chainId` query parameter shared across endpoints. Accepts a chain
+ * alias (`mainnet`/`testnet`) or a numeric chain id, normalizing both to a
+ * numeric {@link ChainId}.
+ */
+export declare const ChainIdQuery: z.ZodMiniOptional<z.ZodMiniPipe<z.ZodMiniUnion<readonly [z.ZodMiniPipe<z.ZodMiniEnum<{
+    mainnet: "mainnet";
+    testnet: "testnet";
+}>, z.ZodMiniTransform<4217 | 42431, "mainnet" | "testnet">>, z.ZodMiniNumber<unknown>]>, z.ZodMiniNumber<number>>>;
+declare const booleanQueryBase: z.ZodMiniPipe<z.ZodMiniEnum<{
+    false: "false";
+    true: "true";
+}>, z.ZodMiniTransform<boolean, "false" | "true">>;
+/**
+ * Boolean query parameter. Query values arrive as the literal strings
+ * `"true"`/`"false"`, validated strictly and transformed to a real boolean.
+ * `z.boolean()` would reject the incoming string outright and
+ * `z.coerce.boolean()` is unsafe (`Boolean("false") === true`).
+ *
+ * The generated JSON Schema is overridden to a plain `boolean` so the parameter
+ * renders as a boolean — not a string — in the OpenAPI docs (and the generated
+ * CLI coerces it), while the wire format and strict `"true"`/`"false"`
+ * validation stay unchanged. The string `enum` that `z.enum` would emit is
+ * dropped (`enum: undefined`): left in place it makes consumers — e.g. the
+ * generated CLI — build a literal-`boolean` enum that then rejects the incoming
+ * string. Wrap with `z.optional(...)` / `z._default(..., value)` and describe
+ * with `.check(z.describe('…'))` at the call site — the override survives both.
+ * Returns a fresh clone per call so each call site is a distinct schema.
+ */
+export declare function booleanQuery(): typeof booleanQueryBase;
+/** One public API error detail. */
+export declare const ErrorDetail: z.ZodMiniObject<{
+    message: z.ZodMiniString<string>;
+    path: z.ZodMiniOptional<z.ZodMiniArray<z.ZodMiniUnion<readonly [z.ZodMiniString<string>, z.ZodMiniNumber<number>]>>>;
+}, z.core.$strip>;
+/**
+ * Builds the global error envelope, optionally enumerating `error.code` to a
+ * fixed set of machine-readable codes. Pass the codes a given status can return
+ * (e.g. `['token_not_found']` for a 404) so the reference and generated clients
+ * narrow the code to a literal union instead of an open `string`. Omit `codes`
+ * for the open-coded envelope.
+ */
+export declare function errorResponse(codes?: readonly [string, ...string[]]): z.ZodMiniObject<{
+    error: z.ZodMiniObject<{
+        code: z.ZodMiniEnum<{
+            [x: string]: string;
+        }> | z.ZodMiniString<string>;
+        details: z.ZodMiniOptional<z.ZodMiniArray<z.ZodMiniObject<{
+            message: z.ZodMiniString<string>;
+            path: z.ZodMiniOptional<z.ZodMiniArray<z.ZodMiniUnion<readonly [z.ZodMiniString<string>, z.ZodMiniNumber<number>]>>>;
+        }, z.core.$strip>>>;
+        message: z.ZodMiniString<string>;
+    }, z.core.$strip>;
+    requestId: z.ZodMiniString<string>;
+}, z.core.$strip>;
+/** Global error envelope with an open-coded `error.code`. */
+export declare const ErrorResponse: z.ZodMiniObject<{
+    error: z.ZodMiniObject<{
+        code: z.ZodMiniEnum<{
+            [x: string]: string;
+        }> | z.ZodMiniString<string>;
+        details: z.ZodMiniOptional<z.ZodMiniArray<z.ZodMiniObject<{
+            message: z.ZodMiniString<string>;
+            path: z.ZodMiniOptional<z.ZodMiniArray<z.ZodMiniUnion<readonly [z.ZodMiniString<string>, z.ZodMiniNumber<number>]>>>;
+        }, z.core.$strip>>>;
+        message: z.ZodMiniString<string>;
+    }, z.core.$strip>;
+    requestId: z.ZodMiniString<string>;
+}, z.core.$strip>;
+/**
+ * Lowercase 0x-prefixed 32-byte hash. The OpenAPI example is attached to the
+ * inner pre-transform schema (path/query params read examples from the pipe
+ * input), so every hash path param surfaces one without per-route overrides.
+ * Callers that need a different example per field build a fresh schema via
+ * `hash(example)` instead of overriding through an outer `.check(z.meta(...))`.
+ */
+export declare const Hash: z.ZodMiniPipe<z.ZodMiniTemplateLiteral<`0x${string}`>, z.ZodMiniTransform<`0x${string}`, `0x${string}`>>;
+/**
+ * Builds a {@link Hash}-shaped schema with the given OpenAPI example. Use when
+ * a path/query param wants a different example than the shared {@link Hash}
+ * default (e.g. a route that documents a specific real transaction).
+ *
+ * The example must be attached to the inner pre-transform schema because
+ * path/query params read examples from the pipe input.
+ */
+export declare function hash(example: core_Hex.Hex): z.ZodMiniPipe<z.ZodMiniTemplateLiteral<`0x${string}`>, z.ZodMiniTransform<`0x${string}`, `0x${string}`>>;
+/** Lowercase 0x-prefixed hex byte data (may be empty, `0x`). */
+export declare const Hex: z.ZodMiniPipe<z.ZodMiniString<string>, z.ZodMiniTransform<`0x${string}`, string>>;
+/** Hex-encoded integer quantity (a `0x`-prefixed integer, e.g. `0x1a`). */
+export declare const Quantity: z.ZodMiniTemplateLiteral<`0x${string}`>;
+/** Non-negative integer as a decimal string (preserves uint256 precision). */
+export declare const DecimalString: z.ZodMiniString<string>;
+/**
+ * Minimum page size accepted across list endpoints. Floored at 5 because the
+ * indexer rejects signature-decoded `Transfer` queries with `LIMIT < 5`
+ * (HTTP 422); applying it globally keeps pagination uniform and removes the need
+ * for per-endpoint clamping.
+ */
+export declare const minLimit = 5;
+/** Page-size query parameter shared across list endpoints. */
+export declare const Limit: z.ZodMiniDefault<z.ZodMiniNumber<unknown>>;
+/** Opaque keyset-pagination cursor query parameter shared across list endpoints. */
+export declare const Cursor: z.ZodMiniOptional<z.ZodMiniString<string>>;
+/**
+ * Maximum page window (`page × limit` rows) accepted by positional pagination.
+ * Mirrors the indexer's own 10k row ceiling, and the bounded-window convention
+ * of comparable APIs (Elasticsearch `max_result_window`, Zendesk's 100-page
+ * cap): shallow page-numbered access is served positionally, deep traversal
+ * must use cursors.
+ */
+export declare const maxPageWindow = 10000;
+/**
+ * Page-number query parameter (1-indexed) shared by list endpoints that
+ * support shallow positional pagination alongside keyset cursors. Cursors
+ * remain the canonical deep-traversal mode; the page lane exists for
+ * page-numbered UIs that need random access into the head of a feed.
+ */
+export declare const Page: z.ZodMiniOptional<z.ZodMiniNumber<unknown>>;
+/**
+ * Cross-field checks for list query schemas that accept both `cursor` and
+ * `page`: the two are mutually exclusive, and the page window is bounded by
+ * {@link maxPageWindow}. Spread into the query object's `.check(...)`.
+ */
+export declare function pageChecks(): readonly [z.core.$ZodCheck<{
+    cursor?: string | undefined;
+    limit: number;
+    page?: number | undefined;
+}>, z.core.$ZodCheck<{
+    cursor?: string | undefined;
+    limit: number;
+    page?: number | undefined;
+}>];
+/** Opaque next-page cursor response field shared across list endpoints. */
+export declare const NextCursor: z.ZodMiniNullable<z.ZodMiniString<string>>;
+/**
+ * Upper bound on the matched-row count surfaced by `include=totalCount`. The
+ * count is computed by a capped subquery (`… LIMIT countCap`) so it can't blow
+ * the indexer's execution budget on the 10⁹-plus row tables; when the bound is
+ * hit the count is a lower bound, signalled by `Meta.totalCountCapped`. Mirrors the
+ * indexer's own 10k row ceiling (see {@link maxPageWindow}) and the capped-count
+ * conventions of comparable APIs (Stripe Search's 10k `total_count`,
+ * Elasticsearch `track_total_hits`, Shopify's `Count.precision`).
+ */
+export declare const countCap = 10000;
+/**
+ * Total matched-row count response field for list endpoints that support
+ * `include=totalCount`. Exact when {@link TotalCountCapped} is `false`; a lower
+ * bound ("at least this many") when `true`. Independent of pagination —
+ * `nextCursor` remains the only end-of-list signal.
+ */
+export declare const TotalCount: z.ZodMiniNumber<number>;
+/**
+ * Whether {@link TotalCount} hit the {@link countCap} bound. `true` means the
+ * count is a lower bound ("at least `totalCount` rows match"); `false` means it
+ * is exact.
+ */
+export declare const TotalCountCapped: z.ZodMiniBoolean<boolean>;
+/** Sort-direction (`asc`/`desc`) query parameter shared across list endpoints. */
+export declare const Order: z.ZodMiniDefault<z.ZodMiniEnum<{
+    asc: "asc";
+    desc: "desc";
+}>>;
+/**
+ * Optional inclusive block-number bound query parameter (`blockNumber.from` /
+ * `blockNumber.to`). `noun` is the resource being listed (e.g. `transfers`) so
+ * the description reads naturally across endpoints.
+ */
+export declare function blockNumberBound(noun: string, bound: 'from' | 'to'): z.ZodMiniOptional<z.ZodMiniNumber<unknown>>;
+/**
+ * Optional inclusive ISO-8601 timestamp bound query parameter (`timestamp.from`
+ * / `timestamp.to`). `noun` is the resource being listed (e.g. `transfers`).
+ */
+export declare function timestampBound(noun: string, bound: 'from' | 'to'): z.ZodMiniOptional<z.ZodMiniISODateTime>;
+/**
+ * Builds the schema for a comma-separated opt-in query parameter (e.g.
+ * `?include=token,feeToken`), parsed into a validated array of the given enum's
+ * members. Absent or empty values yield `[]`. Centralizes the splitting,
+ * trimming, and OpenAPI array-enum metadata that every list endpoint otherwise
+ * repeats.
+ *
+ * A repeated parameter (`?include=token&include=feeToken`) arrives from the
+ * validator as a `string[]`, so the input accepts both forms and each entry is
+ * still comma-split — the two styles compose freely.
+ *
+ * Pass the endpoint's `Include` enum — kept local so its members drive both the
+ * parsed type and the docs — plus the param description.
+ */
+export declare function includeQuery<const T extends Readonly<Record<string, string>>>(member: z.ZodMiniEnum<T>, description: string): z.ZodMiniPipe<z.ZodMiniPipe<z.ZodMiniOptional<z.ZodMiniUnknown>, z.ZodMiniTransform<string[], unknown>>, z.ZodMiniArray<z.ZodMiniEnum<T>>>;
+/**
+ * Ready-made `include` query parameter for list endpoints whose only optional
+ * resource is the capped total count (`?include=totalCount`). Endpoints that
+ * embed additional resources define their own enum that also lists `totalCount`
+ * (e.g. transfers' `memo,token,totalCount`).
+ */
+export declare const totalCountInclude: z.ZodMiniPipe<z.ZodMiniPipe<z.ZodMiniOptional<z.ZodMiniUnknown>, z.ZodMiniTransform<string[], unknown>>, z.ZodMiniArray<z.ZodMiniEnum<{
+    totalCount: "totalCount";
+}>>>;
+/**
+ * Response-wide `meta` object for list endpoints whose only embeddable resource
+ * is the capped total count. Present only when `include=totalCount` was
+ * requested; omitted otherwise. Endpoints that embed additional response-wide
+ * resources alongside the count define their own `Meta` that also carries
+ * {@link TotalCount}/{@link TotalCountCapped}.
+ */
+export declare const CountMeta: z.ZodMiniObject<{
+    totalCountCapped: z.ZodMiniBoolean<boolean>;
+    totalCount: z.ZodMiniNumber<number>;
+}, z.core.$strip>;
+export {};
+//# sourceMappingURL=Schema.d.ts.map

package/dist/internal/Schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Schema.d.ts","sourceRoot":"","sources":["../../src/internal/Schema.ts"],"names":[],"mappings":"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"}