stitchkit 0.70.6 → 0.72.0

package/dist/server/index.d.ts

@@ -20,7 +20,7 @@ export { bindProcessSignals, type ProcessSignalName, type ProcessSignalsBinding,
 export { createRateLimiter, type RateLimitConfig } from './rate-limit.js';
 export { errorResponse, parseBody, respondJson } from './raw.js';
 export { bindRealtimeServer, type RealtimeServer, type RealtimeServerConnection, type RealtimeServerHandle, } from './realtime.js';
-export { type ClientIpOptions, extractIp, generateTraceId, getClientInfo, resolveSocketIp, resolveTraceId, } from './request.js';
+export { type ClientIpOptions, extractIp, generateTraceId, getClientInfo, isPublicIp, resolveSocketIp, resolveTraceId, } from './request.js';
 export { type ManagedServerHandle, type ShutdownOptions, ShutdownOptionsSchema, type ShutdownResult, ShutdownResultSchema, type ShutdownState, ShutdownStateSchema, type ShutdownStatus, ShutdownStatusSchema, } from './shutdown.js';
 export type { SocketIOHandshakeConfig, SocketIOPeerLoaders, SocketIORequestPolicy, SocketIOServerConfig, SocketIOServerHandle, SocketIOServerLifecycle, } from './socket-io.js';
 export { createSocketIOServer, socketIoLane } from './socket-io.js';

package/dist/server/index.d.ts.map

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

package/dist/server/index.js

@@ -13,7 +13,7 @@ import {
   sseRoute,
   streamingRoute,
   webSocketLane
-} from "../index-cx84zg25.js";
+} from "../index-118v0z41.js";
 import {
   composeAuthHooks,
   createAuthHook,
@@ -46,9 +46,10 @@ import {
   generateTraceId,
   getClientInfo,
   getTraceId,
+  isPublicIp,
   resolveSocketIp,
   resolveTraceId
-} from "../index-w9m1wznn.js";
+} from "../index-nemjkxjp.js";
 import {
   isWithinDir,
   realPathWithinDir
@@ -1007,6 +1008,7 @@ export {
   ndjsonRoute,
   isWithinDir,
   isStitchErrorCode,
+  isPublicIp,
   implementRegistry,
   implement,
   getClientInfo,

package/dist/server/request.d.ts

@@ -42,4 +42,23 @@ export declare function getClientInfo(req: Request, options?: ClientIpOptions):
 };
 /** Flatten a URL query string — repeated keys collapse to arrays. */
 export declare function parseQueryParams(url: URL): Record<string, string | string[]>;
+/**
+ * Whether an address belongs to the public internet.
+ *
+ * The question behind it is always the same one: *may this address be handed to
+ * something outside this process* — resolved against a third party, fetched
+ * from, recorded as where a request came from. A loopback, a private LAN
+ * address, a carrier-NAT address or a link-local one answer no, each for its
+ * own reason, and none of them identifies a host anyone else can reach.
+ *
+ * **Anything it cannot parse is not public.** An empty string, a hostname, a
+ * truncated address: the honest answer to "is this a public peer" is no, and a
+ * function that returned `true` for a value it did not understand would be
+ * safe-by-accident exactly until the first malformed header.
+ *
+ * IPv4-mapped IPv6 (`::ffff:10.0.0.1`) is judged as the IPv4 address it
+ * carries — the mapping is notation, not a different host. Pair it with
+ * `extractIp`, which produces the value this asks about.
+ */
+export declare function isPublicIp(value: string): boolean;
 //# sourceMappingURL=request.d.ts.map

package/dist/server/request.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"request.d.ts","sourceRoot":"","sources":["../../src/server/request.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAKH,6EAA6E;AAC7E,wBAAgB,eAAe,IAAI,MAAM,CAExC;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,CASnD;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAejF;AAED,iDAAiD;AACjD,MAAM,WAAW,eAAe;IAC9B;;;;OAIG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,uDAAuD;IACvD,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,GAAG,EAAE,OAAO,EAAE,OAAO,GAAE,eAAoB,GAAG,MAAM,CAQ7E;AAED,6EAA6E;AAC7E,wBAAgB,aAAa,CAC3B,GAAG,EAAE,OAAO,EACZ,OAAO,GAAE,eAAoB,GAC5B;IACD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,CAKA;AAED,qEAAqE;AACrE,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,GAAG,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC,CAU5E"}
+{"version":3,"file":"request.d.ts","sourceRoot":"","sources":["../../src/server/request.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAKH,6EAA6E;AAC7E,wBAAgB,eAAe,IAAI,MAAM,CAExC;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,CASnD;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAejF;AAED,iDAAiD;AACjD,MAAM,WAAW,eAAe;IAC9B;;;;OAIG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,uDAAuD;IACvD,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,GAAG,EAAE,OAAO,EAAE,OAAO,GAAE,eAAoB,GAAG,MAAM,CAQ7E;AAED,6EAA6E;AAC7E,wBAAgB,aAAa,CAC3B,GAAG,EAAE,OAAO,EACZ,OAAO,GAAE,eAAoB,GAC5B;IACD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,CAKA;AAED,qEAAqE;AACrE,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,GAAG,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC,CAU5E;AAgGD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CA+BjD"}

package/dist/telegram/init-data.d.ts

@@ -0,0 +1,134 @@
+/**
+ * Who a Telegram Mini App request is from, proved rather than believed.
+ *
+ * A Mini App hands its backend an `initData` string. Telegram signs it with a
+ * key derived from the bot token, so a backend that checks the signature knows
+ * the user; a backend that reads `initDataUnsafe` and trusts it has an open
+ * door — the string is fully client-controlled, and the name Telegram gave that
+ * field is the whole warning.
+ *
+ * Three consuming applications wrote this check independently. Two of the three
+ * files agree closely enough to have shared an ancestor, and the third had
+ * drifted: the algorithm is short, published, and easy to get *almost* right.
+ * Almost right is the failure mode worth removing — a comparison that returns
+ * early on the first differing byte, an expiry checked before the signature, a
+ * `user` field read out of the string before anything proved it was ours.
+ *
+ * **This verifies; it does not phrase and it does not decide.** What a rejected
+ * request should answer, whether an expired one may re-authenticate, which
+ * fields a session keeps — those belong to the application. What the core owes
+ * is the distinction between *authentic* and *not*, and the reason when not.
+ *
+ * Not a domain model (→ ADR 0002): "Telegram signed this string" is a fact
+ * about a transport, the same kind of fact as a bearer token being well-formed.
+ */
+import { z } from 'zod';
+/**
+ * The Telegram user record, as our surface names things.
+ *
+ * Telegram's wire fields are `snake_case`; every other name this package
+ * publishes is `camelCase`, and a surface that switches convention because of
+ * where a value came from makes the caller remember which is which. The
+ * untouched wire pairs stay available in `raw`.
+ */
+declare const TelegramInitDataUserSchema: z.ZodPipe<z.ZodObject<{
+    id: z.ZodInt;
+    is_bot: z.ZodOptional<z.ZodBoolean>;
+    first_name: z.ZodString;
+    last_name: z.ZodOptional<z.ZodString>;
+    username: z.ZodOptional<z.ZodString>;
+    language_code: z.ZodOptional<z.ZodString>;
+    is_premium: z.ZodOptional<z.ZodBoolean>;
+    allows_write_to_pm: z.ZodOptional<z.ZodBoolean>;
+    photo_url: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, z.ZodTransform<{
+    id: number;
+    firstName: string;
+    isBot?: boolean | undefined;
+    lastName?: string | undefined;
+    username?: string | undefined;
+    languageCode?: string | undefined;
+    isPremium?: boolean | undefined;
+    allowsWriteToPm?: boolean | undefined;
+    photoUrl?: string | undefined;
+}, {
+    id: number;
+    is_bot?: boolean | undefined;
+    first_name: string;
+    last_name?: string | undefined;
+    username?: string | undefined;
+    language_code?: string | undefined;
+    is_premium?: boolean | undefined;
+    allows_write_to_pm?: boolean | undefined;
+    photo_url?: string | undefined;
+}>>;
+export type TelegramInitDataUser = z.infer<typeof TelegramInitDataUserSchema>;
+export interface TelegramInitData {
+    /** Absent when the Mini App was opened somewhere Telegram sends no user. */
+    user?: TelegramInitDataUser;
+    /** Whose chat the Mini App was opened from, when Telegram named one. */
+    receiver?: TelegramInitDataUser;
+    /** When Telegram signed this string. */
+    authDate: Date;
+    /** How old the signature was at verification time. */
+    ageSeconds: number;
+    queryId?: string;
+    startParam?: string;
+    chatType?: string;
+    chatInstance?: string;
+    /**
+     * Every signed pair exactly as Telegram sent it, `hash` excluded.
+     *
+     * Telegram adds fields without warning, and a caller that needs one this
+     * release has never heard of should not have to wait for a release to read
+     * it. Everything here was covered by the signature.
+     */
+    raw: Readonly<Record<string, string>>;
+}
+/**
+ * Why a string was not accepted.
+ *
+ * `signature-mismatch` is the only one that means someone tampered; the others
+ * are shapes a legitimate client can produce, and an application may well
+ * answer them differently — an expired string is a re-open, a malformed one is
+ * a bug report.
+ */
+export type TelegramInitDataRefusal = 'missing-hash' | 'signature-mismatch' | 'malformed' | 'expired';
+export type TelegramInitDataVerification = {
+    readonly valid: true;
+    readonly data: TelegramInitData;
+} | {
+    readonly valid: false;
+    readonly reason: TelegramInitDataRefusal;
+    /** Present on `expired`, where the number is the point of the refusal. */
+    readonly ageSeconds?: number;
+};
+export interface VerifyTelegramInitDataOptions {
+    /** The raw query-string Telegram handed the Mini App. */
+    initData: string;
+    /** The bot the Mini App belongs to. Never leaves this function. */
+    botToken: string;
+    /**
+     * Refuse a signature older than this many seconds.
+     *
+     * A signed string stays valid forever unless something bounds it, so a
+     * captured one is a permanent credential. Omitted means no bound, which is a
+     * deliberate choice rather than a default: only the application knows how
+     * long its own session is worth.
+     */
+    maxAgeSeconds?: number;
+    /** Epoch milliseconds, for a caller that owns its own clock. */
+    now?: () => number;
+}
+/**
+ * Verify one `initData` string and report what it says.
+ *
+ * Never throws for anything a client can send: a string that fails is a
+ * refusal with a reason, because the caller has to answer the request either
+ * way and an exception for the ordinary case turns every handler into a
+ * `try`/`catch`. A missing bot token is not that case — it is this process
+ * being configured wrong, and it throws.
+ */
+export declare function verifyTelegramInitData(options: VerifyTelegramInitDataOptions): Promise<TelegramInitDataVerification>;
+export {};
+//# sourceMappingURL=init-data.d.ts.map

package/dist/telegram/init-data.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"init-data.d.ts","sourceRoot":"","sources":["../../src/telegram/init-data.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;;;GAOG;AACH,QAAA,MAAM,0BAA0B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsB3B,CAAC;AAEN,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,0BAA0B,CAAC,CAAC;AAE9E,MAAM,WAAW,gBAAgB;IAC/B,4EAA4E;IAC5E,IAAI,CAAC,EAAE,oBAAoB,CAAC;IAC5B,wEAAwE;IACxE,QAAQ,CAAC,EAAE,oBAAoB,CAAC;IAChC,wCAAwC;IACxC,QAAQ,EAAE,IAAI,CAAC;IACf,sDAAsD;IACtD,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;;;;OAMG;IACH,GAAG,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CACvC;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,uBAAuB,GAC/B,cAAc,GACd,oBAAoB,GACpB,WAAW,GACX,SAAS,CAAC;AAEd,MAAM,MAAM,4BAA4B,GACpC;IAAE,QAAQ,CAAC,KAAK,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,gBAAgB,CAAA;CAAE,GACzD;IACE,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,uBAAuB,CAAC;IACzC,0EAA0E;IAC1E,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAC9B,CAAC;AAEN,MAAM,WAAW,6BAA6B;IAC5C,yDAAyD;IACzD,QAAQ,EAAE,MAAM,CAAC;IACjB,mEAAmE;IACnE,QAAQ,EAAE,MAAM,CAAC;IACjB;;;;;;;OAOG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,gEAAgE;IAChE,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACpB;AAiDD;;;;;;;;GAQG;AACH,wBAAsB,sBAAsB,CAC1C,OAAO,EAAE,6BAA6B,GACrC,OAAO,CAAC,4BAA4B,CAAC,CAuEvC"}

package/dist/telegram/send-failure.d.ts

@@ -0,0 +1,73 @@
+/**
+ * What a refused Telegram send was, as a fact rather than as a sentence.
+ *
+ * Two consuming applications carry the same broadcast subsystem — three of its
+ * files byte-identical — and inside it the same list of substrings: *bot was
+ * blocked*, *user is deactivated*, *chat not found*. The list exists because
+ * the Bot API answers a permanently unreachable recipient and a temporarily
+ * throttled one with the same shape, and a sender that cannot tell them apart
+ * either retries a user who will never receive anything or drops one who would
+ * have.
+ *
+ * The two questions are separate on purpose. `retryable` asks whether *this
+ * send* could work if repeated; `recipientUnreachable` asks whether *this
+ * recipient* should be addressed again at all. A rate limit is the first
+ * without the second; a blocked user is the second without the first; a
+ * message Telegram could not parse is neither — the recipient is fine and it is
+ * our payload that is wrong, which is exactly the case a substring list marks
+ * as a delivery failure and quietly counts against the wrong party.
+ *
+ * **This classifies; it does not act.** Whether to retry, how long to wait,
+ * whether a blocked user is deleted or merely flagged — the application's,
+ * along with every sentence a human reads. → ADR 0141.
+ */
+/**
+ * Why a send did not arrive.
+ *
+ * Each member earns its name by implying a different next move. The four that
+ * mean "not this recipient" are not folded together: a deactivated account is
+ * gone and its row can be closed, a block can be lifted and the row is kept, a
+ * user who never pressed Start needs an invitation rather than a retry, and a
+ * chat Telegram does not know is usually a bad identifier on our side — a
+ * defect in our data, not a fact about a person.
+ */
+export type TelegramSendFailureReason = 'blocked-by-user' | 'user-deactivated' | 'chat-not-found' | 'not-started' | 'rate-limited' | 'message-invalid' | 'server-error' | 'unknown';
+export interface TelegramSendFailure {
+    reason: TelegramSendFailureReason;
+    /** Telegram's `error_code`, when the failure carried one. */
+    status?: number;
+    /**
+     * How long Telegram asked us to wait, from its own `parameters.retry_after`.
+     *
+     * Only ever present when Telegram said it. A sender that needs a number
+     * anyway picks its own backoff; inventing one here would put a guess and a
+     * statement in the same field.
+     */
+    retryAfterSeconds?: number;
+    /** Repeating this same send could plausibly succeed. */
+    retryable: boolean;
+    /**
+     * This recipient will not receive this or any later message until something
+     * outside our control changes, so a broadcast should stop addressing them.
+     *
+     * Asserted only for the reasons that actually establish it. An unrecognised
+     * refusal leaves it `false`: marking a recipient unreachable on a guess is
+     * how a working subscriber is silently dropped forever, and that error is
+     * far more expensive than one wasted send.
+     */
+    recipientUnreachable: boolean;
+    /**
+     * How the reason was reached. `parameters` and `status` are Telegram stating
+     * its own answer in a structured field; `description` is us reading its
+     * prose, which changes without notice.
+     */
+    evidence: 'parameters' | 'status' | 'description' | 'none';
+}
+/**
+ * Classify one refused send.
+ *
+ * Never throws and never guesses: a refusal it does not recognise is `unknown`,
+ * which asserts nothing about the recipient and permits no retry.
+ */
+export declare function classifyTelegramSendFailure(error: unknown): TelegramSendFailure;
+//# sourceMappingURL=send-failure.d.ts.map

package/dist/telegram/send-failure.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"send-failure.d.ts","sourceRoot":"","sources":["../../src/telegram/send-failure.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAIH;;;;;;;;;GASG;AACH,MAAM,MAAM,yBAAyB,GACjC,iBAAiB,GACjB,kBAAkB,GAClB,gBAAgB,GAChB,aAAa,GACb,cAAc,GACd,iBAAiB,GACjB,cAAc,GACd,SAAS,CAAC;AAEd,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,yBAAyB,CAAC;IAClC,6DAA6D;IAC7D,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;;;OAMG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,wDAAwD;IACxD,SAAS,EAAE,OAAO,CAAC;IACnB;;;;;;;;OAQG;IACH,oBAAoB,EAAE,OAAO,CAAC;IAC9B;;;;OAIG;IACH,QAAQ,EAAE,YAAY,GAAG,QAAQ,GAAG,aAAa,GAAG,MAAM,CAAC;CAC5D;AAuED;;;;;GAKG;AACH,wBAAgB,2BAA2B,CAAC,KAAK,EAAE,OAAO,GAAG,mBAAmB,CA0D/E"}

package/dist/telegram.d.ts

@@ -0,0 +1,3 @@
+export { type TelegramInitData, type TelegramInitDataRefusal, type TelegramInitDataUser, type TelegramInitDataVerification, type VerifyTelegramInitDataOptions, verifyTelegramInitData, } from './telegram/init-data.js';
+export { classifyTelegramSendFailure, type TelegramSendFailure, type TelegramSendFailureReason, } from './telegram/send-failure.js';
+//# sourceMappingURL=telegram.d.ts.map

package/dist/telegram.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"telegram.d.ts","sourceRoot":"","sources":["../src/telegram.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,gBAAgB,EACrB,KAAK,uBAAuB,EAC5B,KAAK,oBAAoB,EACzB,KAAK,4BAA4B,EACjC,KAAK,6BAA6B,EAClC,sBAAsB,GACvB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EACL,2BAA2B,EAC3B,KAAK,mBAAmB,EACxB,KAAK,yBAAyB,GAC/B,MAAM,yBAAyB,CAAC"}

package/dist/telegram.js

@@ -0,0 +1,224 @@
+import {
+  isRecord
+} from "./index-qyrqwr4c.js";
+
+// src/telegram/init-data.ts
+import { z } from "zod";
+var TelegramInitDataUserSchema = z.object({
+  id: z.int(),
+  is_bot: z.boolean().optional(),
+  first_name: z.string(),
+  last_name: z.string().optional(),
+  username: z.string().optional(),
+  language_code: z.string().optional(),
+  is_premium: z.boolean().optional(),
+  allows_write_to_pm: z.boolean().optional(),
+  photo_url: z.string().optional()
+}).transform((user) => ({
+  id: user.id,
+  firstName: user.first_name,
+  ...user.is_bot !== undefined && { isBot: user.is_bot },
+  ...user.last_name !== undefined && { lastName: user.last_name },
+  ...user.username !== undefined && { username: user.username },
+  ...user.language_code !== undefined && { languageCode: user.language_code },
+  ...user.is_premium !== undefined && { isPremium: user.is_premium },
+  ...user.allows_write_to_pm !== undefined && { allowsWriteToPm: user.allows_write_to_pm },
+  ...user.photo_url !== undefined && { photoUrl: user.photo_url }
+}));
+var encoder = new TextEncoder;
+async function hmacSha256(key, message) {
+  const imported = await crypto.subtle.importKey("raw", key, { name: "HMAC", hash: "SHA-256" }, false, ["sign"]);
+  return crypto.subtle.sign("HMAC", imported, encoder.encode(message));
+}
+function toHex(buffer) {
+  return Array.from(new Uint8Array(buffer), (byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+function digestsEqual(a, b) {
+  if (a.length !== b.length)
+    return false;
+  let difference = 0;
+  for (let index = 0;index < a.length; index += 1) {
+    difference |= a.charCodeAt(index) ^ b.charCodeAt(index);
+  }
+  return difference === 0;
+}
+function optionalUser(raw, key) {
+  const encoded = raw[key];
+  if (encoded === undefined)
+    return;
+  return TelegramInitDataUserSchema.parse(JSON.parse(encoded));
+}
+async function verifyTelegramInitData(options) {
+  if (!options.botToken)
+    throw new TypeError("botToken is required to verify initData");
+  if (options.maxAgeSeconds !== undefined && (!Number.isFinite(options.maxAgeSeconds) || options.maxAgeSeconds < 0)) {
+    throw new TypeError("maxAgeSeconds must be a non-negative finite number");
+  }
+  const params = new URLSearchParams(options.initData);
+  const hash = params.get("hash");
+  if (!hash)
+    return { valid: false, reason: "missing-hash" };
+  const signed = {};
+  for (const [key, value] of params) {
+    if (key === "hash")
+      continue;
+    signed[key] = value;
+  }
+  const dataCheckString = Object.keys(signed).sort().map((key) => `${key}=${signed[key]}`).join(`
+`);
+  const secretKey = await hmacSha256(encoder.encode("WebAppData"), options.botToken);
+  const expected = toHex(await hmacSha256(secretKey, dataCheckString));
+  if (!digestsEqual(expected, hash.toLowerCase())) {
+    return { valid: false, reason: "signature-mismatch" };
+  }
+  const authDateSeconds = Number(signed.auth_date);
+  if (!Number.isSafeInteger(authDateSeconds) || authDateSeconds <= 0) {
+    return { valid: false, reason: "malformed" };
+  }
+  const nowMs = options.now?.() ?? Date.now();
+  const ageSeconds = Math.floor(nowMs / 1000) - authDateSeconds;
+  if (options.maxAgeSeconds !== undefined && ageSeconds > options.maxAgeSeconds) {
+    return { valid: false, reason: "expired", ageSeconds };
+  }
+  let user;
+  let receiver;
+  try {
+    user = optionalUser(signed, "user");
+    receiver = optionalUser(signed, "receiver");
+  } catch {
+    return { valid: false, reason: "malformed" };
+  }
+  return {
+    valid: true,
+    data: {
+      ...user !== undefined && { user },
+      ...receiver !== undefined && { receiver },
+      authDate: new Date(authDateSeconds * 1000),
+      ageSeconds,
+      ...signed.query_id !== undefined && { queryId: signed.query_id },
+      ...signed.start_param !== undefined && { startParam: signed.start_param },
+      ...signed.chat_type !== undefined && { chatType: signed.chat_type },
+      ...signed.chat_instance !== undefined && { chatInstance: signed.chat_instance },
+      raw: Object.freeze({ ...signed })
+    }
+  };
+}
+// src/telegram/send-failure.ts
+var BY_DESCRIPTION = [
+  [/bot was blocked by the user|bot was kicked/i, "blocked-by-user"],
+  [/user is deactivated|account is deactivated/i, "user-deactivated"],
+  [/can'?t initiate conversation|need to start a conversation/i, "not-started"],
+  [/chat not found|peer_id_invalid|user not found/i, "chat-not-found"],
+  [/too many requests|retry later|flood/i, "rate-limited"],
+  [
+    /message is too long|can'?t parse entities|message text is empty|wrong file identifier|button_url_invalid/i,
+    "message-invalid"
+  ]
+];
+var RETRYABLE = new Set([
+  "rate-limited",
+  "server-error"
+]);
+var UNREACHABLE = new Set([
+  "blocked-by-user",
+  "user-deactivated",
+  "chat-not-found",
+  "not-started"
+]);
+function numberAt(value, keys) {
+  if (!isRecord(value))
+    return;
+  for (const key of keys) {
+    const candidate = value[key];
+    if (typeof candidate === "number" && Number.isFinite(candidate))
+      return candidate;
+  }
+  return;
+}
+function statusOf(value, depth = 0) {
+  if (!isRecord(value) || depth > 4)
+    return;
+  const direct = numberAt(value, ["error_code", "statusCode", "status"]);
+  if (direct !== undefined && direct >= 400 && direct < 600)
+    return direct;
+  const nested = value.cause ?? value.response ?? value.error;
+  return nested === value ? undefined : statusOf(nested, depth + 1);
+}
+function retryAfterOf(value, depth = 0) {
+  if (!isRecord(value) || depth > 4)
+    return;
+  const direct = numberAt(value.parameters, ["retry_after"]);
+  if (direct !== undefined)
+    return direct;
+  const nested = value.cause ?? value.response ?? value.error;
+  return nested === value ? undefined : retryAfterOf(nested, depth + 1);
+}
+function descriptionOf(value, depth = 0) {
+  if (typeof value === "string")
+    return value;
+  if (value instanceof Error) {
+    const nested2 = isRecord(value) ? descriptionOf(value.cause, depth + 1) : "";
+    return `${value.message} ${nested2}`.trim();
+  }
+  if (!isRecord(value) || depth > 4)
+    return "";
+  const own = typeof value.description === "string" ? value.description : "";
+  const message = typeof value.message === "string" ? value.message : "";
+  const nested = descriptionOf(value.cause ?? value.response ?? value.error, depth + 1);
+  return [own, message, nested].filter(Boolean).join(" ");
+}
+function classifyTelegramSendFailure(error) {
+  const status = statusOf(error);
+  const retryAfterSeconds = retryAfterOf(error);
+  const description = descriptionOf(error);
+  if (retryAfterSeconds !== undefined) {
+    return {
+      reason: "rate-limited",
+      ...status !== undefined && { status },
+      retryAfterSeconds,
+      retryable: true,
+      recipientUnreachable: false,
+      evidence: "parameters"
+    };
+  }
+  for (const [pattern, reason] of BY_DESCRIPTION) {
+    if (pattern.test(description)) {
+      return {
+        reason,
+        ...status !== undefined && { status },
+        retryable: RETRYABLE.has(reason),
+        recipientUnreachable: UNREACHABLE.has(reason),
+        evidence: "description"
+      };
+    }
+  }
+  if (status === 429) {
+    return {
+      reason: "rate-limited",
+      status,
+      retryable: true,
+      recipientUnreachable: false,
+      evidence: "status"
+    };
+  }
+  if (status !== undefined && status >= 500) {
+    return {
+      reason: "server-error",
+      status,
+      retryable: true,
+      recipientUnreachable: false,
+      evidence: "status"
+    };
+  }
+  return {
+    reason: "unknown",
+    ...status !== undefined && { status },
+    retryable: false,
+    recipientUnreachable: false,
+    evidence: "none"
+  };
+}
+export {
+  verifyTelegramInitData,
+  classifyTelegramSendFailure
+};

package/dist/tool-invoker.js

@@ -1,9 +1,9 @@
 import {
   createToolInvoker
-} from "./index-ekkt4gy9.js";
-import"./index-ejv31h14.js";
-import"./index-qm87g51s.js";
-import"./index-w9m1wznn.js";
+} from "./index-jqtsc9mj.js";
+import"./index-7qy2ex0m.js";
+import"./index-s4c8wy8m.js";
+import"./index-nemjkxjp.js";
 import"./index-22by16v6.js";
 import"./index-cby4ar3v.js";
 import"./index-nt1mp8km.js";

package/dist/tools.js

@@ -4,7 +4,7 @@ import {
 import {
   buildToolManifest,
   mountAgent
-} from "./index-trrf7nch.js";
+} from "./index-ezmn6ac6.js";
 import"./index-3xnq72rz.js";
 import {
   signJwt,
@@ -20,7 +20,7 @@ import {
 } from "./index-vbf2p6me.js";
 import {
   createToolInvoker
-} from "./index-ekkt4gy9.js";
+} from "./index-jqtsc9mj.js";
 import {
   WaitTimeoutError,
   createCli,
@@ -29,10 +29,10 @@ import {
   fetchPinnedDocument,
   readCapped,
   runWaitOperation
-} from "./index-tnazr5tc.js";
+} from "./index-pz7ytdga.js";
 import {
   collectToolSurface
-} from "./index-hxtm2xr2.js";
+} from "./index-k2zczx1g.js";
 import {
   createRuntimeToolFactory,
   defineRuntimeTool
@@ -41,19 +41,19 @@ import {
   collectTools,
   createToolRunner,
   formatToolError
-} from "./index-ejv31h14.js";
+} from "./index-7qy2ex0m.js";
 import {
   ToolExecutionControlError,
   coerceJsonArgs,
   executeToolMethod,
   isToolExecutionControlError,
   toolResultFromError
-} from "./index-qm87g51s.js";
+} from "./index-s4c8wy8m.js";
 import {
   getRequestContext,
   getTraceId,
   runWithRequestContext
-} from "./index-w9m1wznn.js";
+} from "./index-nemjkxjp.js";
 import {
   ManagedFileError
 } from "./index-bfcpjw20.js";