listo-delivery 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Cheto Labs, S.A.P.I. de C.V.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,183 @@
-# Temporary Holding Version
+# listo-delivery
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The official TypeScript SDK for the [Listo Delivery API](https://docs.listo.delivery).
+It has no runtime dependencies: it uses the global `fetch` and `node:crypto`, and runs on Node 18 or later.
+
+The types, the request code and the resources are generated from the published
+OpenAPI schema, so a field the API documents is a field you get.
+
+## Install
+
+```sh
+npm i listo-delivery
+```
+
+## Quickstart: quote and book a test delivery
+
+A key that starts with `lst_test_` dispatches simulated couriers and moves no
+money. `lst_live_` books real ones. The prefix decides the mode: `listo.mode`
+is `"test"` or `"live"`, and there is no separate option.
+
+```ts
+import { Listo } from "listo-delivery";
+
+const listo = new Listo({ apiKey: process.env.LISTO_API_KEY! });
+
+const quote = await listo.quotes.create({
+  store_id: "st_...",
+  dropoff: { street: "Av. Vallarta 1234, Guadalajara" },
+});
+
+const delivery = await listo.deliveries.create(
+  {
+    store_id: "st_...",
+    quote_id: quote.id,
+    external_id: "order-841", // your own order id
+    payment_method: "prepaid",
+    order_value_cents: 18000,
+    dropoff: { name: "Ana", phone: "+523312345678", street: "Av. Vallarta 1234, Guadalajara" },
+  },
+  { idempotencyKey: "order-841" },
+);
+
+console.log(delivery.id, delivery.status);
+```
+
+A file that uses top-level `await`, like this one, needs `"type": "module"` in
+your project's `package.json` for `tsc` to accept it (Node runs it either way).
+
+Field names are the wire names (`store_id`, `order_value_cents`). Every call is
+`listo.<resource>.<method>(...pathValues, bodyOrQuery?, options?)`: path values
+come first, in path order, then one object (the body of a write, the query of a
+read), then the options. A body the schema requires is a required argument.
+
+```ts
+await listo.deliveries.retrieve("dlv_...");
+await listo.deliveries.cancel("dlv_...", { reason: "customer_canceled" });
+await listo.ledger.listForStore("st_...", { cursor });
+await listo.ping();
+```
+
+Every operation of the API is a method, named after it and camel-cased here
+(`listo.requestLogs`, `listo.cardOnboarding.createForStore`, ...); the API reference at
+[docs.listo.delivery](https://docs.listo.delivery) lists them all.
+
+## Verify a webhook
+
+Verify the RAW body exactly as it arrived, before any JSON parsing. A parsed and
+re-serialised body has different bytes and will not match.
+
+```ts
+import express from "express";
+import { Listo, ListoError } from "listo-delivery";
+
+const app = express();
+
+app.post("/webhooks/listo", express.raw({ type: "application/json" }), (req, res) => {
+  try {
+    const event = Listo.webhooks.constructEvent(
+      req.body, // a Buffer
+      req.header("X-Listo-Signature"),
+      [process.env.LISTO_WEBHOOK_SECRET!], // two during a secret rotation
+    );
+    if (event.type === "delivery.status_changed") {
+      console.log(event.data.id, event.data.status); // narrowed to a Delivery
+    }
+    res.sendStatus(204);
+  } catch (error) {
+    // ListoError covers both refusals: invalid_signature (ListoSignatureError)
+    // and invalid_payload (a signed body that is not a JSON object).
+    if (error instanceof ListoError) return void res.sendStatus(400);
+    throw error;
+  }
+});
+```
+
+`Listo.webhooks` (also exported as `webhooks`) needs no API key. The same two
+functions are on `listo.webhooks` next to the API's own webhook calls.
+
+- `verify(rawBody, header, secrets, { tolerance?, now? })` returns a boolean and never throws.
+  The header must be `t=<unix seconds>,v1=<hex>`; the signed string is `"<t>.<raw body>"`;
+  a timestamp more than 300 seconds from now in either direction is refused, and so is
+  an upper-case signature. Blank secrets are ignored; with none left the answer is `false`.
+- `constructEvent(...)` verifies, then parses the body into the `WebhookEvent` union,
+  discriminated on `type`. It throws `ListoSignatureError` (a `ListoError` with code
+  `invalid_signature`) on a bad signature, and a `ListoError` with code `invalid_payload`
+  when the signed body is not a JSON object. Beyond that it does not check the shape:
+  an event comes back as it arrived, typed by its `type` (the TypeScript types describe it,
+  they do not validate it), and one whose `type` this SDK does not know yet is not an
+  error either, so keep a default branch when you switch on `type`.
+
+## Errors
+
+Every refusal and failure is one class, `ListoError`. Branch on `code`, never on `message`.
+
+```ts
+import { ListoError, ListoConnectionError } from "listo-delivery";
+
+try {
+  await listo.deliveries.create(body);
+} catch (error) {
+  if (error instanceof ListoConnectionError) {
+    // No answer (DNS, refused, timeout). A write may have happened: retry with the SAME idempotency key.
+  } else if (error instanceof ListoError) {
+    console.log(error.code, error.status, error.param, error.retryable, error.requestId, error.docUrl);
+  }
+}
+```
+
+Fields: `code`, `message`, `param`, `retryable`, `status`, `requestId`, `docUrl`, and the
+parsed response `body`. (Python and Ruby spell the last two `request_id` and `doc_url`.)
+A response that is not the API's error envelope (an HTML page from a proxy) is still a
+`ListoError`, with `code: "http_<status>"`. The API key is never put in an error message.
+
+## Idempotency
+
+The operations whose schema takes an `Idempotency-Key` header (creating a delivery, a
+refund, creating a store, reactivating or cancelling a store's plan) always send one:
+yours when you pass `{ idempotencyKey }` (key it on your own order id; an empty or blank
+key throws a `TypeError` before any request), otherwise a fresh UUID for that call.
+Repeating a call with the same key within 24 hours returns the original answer instead of
+doing the work again. No other operation sends the header, and passing `idempotencyKey` to
+one is a compile-time error (and a `TypeError` before any request in plain JavaScript),
+never silently dropped.
+
+## Pagination
+
+List calls return the page as the schema has it: `data`, `has_more` and `cursor`.
+Pass `cursor` back to get the next page.
+
+```ts
+let cursor: string | undefined;
+do {
+  const page = await listo.deliveries.list({ status: "delivered", cursor });
+  for (const delivery of page.data) console.log(delivery.id);
+  cursor = page.has_more && page.cursor ? page.cursor : undefined;
+} while (cursor);
+```
+
+## Retries and timeouts
+
+Nothing is retried by default. With `maxRetries: n`, only a `429` is retried, up to `n`
+times, after the `Retry-After` wait (seconds or an HTTP date; 1 second when missing or
+unreadable; never more than 60), with the same idempotency key. A `5xx` or a dropped
+connection is never retried automatically, because a write may have happened.
+
+```ts
+const listo = new Listo({
+  apiKey,
+  maxRetries: 2,
+  timeoutMs: 30_000, // per attempt, the default
+  baseUrl: "https://api.listo.delivery", // the default
+  fetch: customFetch, // optional; receives a Request
+});
+```
+
+A call also takes `{ signal }` to abort it.
+
+## About this repository
+
+This code is generated from Listo's API definition. Issues and questions are
+welcome in this repository. Changes are made upstream by Listo and released
+here, so a pull request cannot be merged as it stands: open an issue and the
+change is made at the source.

package/dist/client.d.ts

@@ -0,0 +1,17 @@
+import type { ListoOptions } from "./http.ts";
+import { Resources, WebhooksResource } from "./resources.gen.ts";
+import type { WebhookVerifier } from "./webhooks.ts";
+/** `listo.webhooks`: the API's webhook calls (send a test, read delivery attempts) plus the signature helpers. */
+export declare class ListoWebhooks extends WebhooksResource {
+    verify(...args: Parameters<WebhookVerifier["verify"]>): boolean;
+    constructEvent(...args: Parameters<WebhookVerifier["constructEvent"]>): ReturnType<WebhookVerifier["constructEvent"]>;
+}
+export declare class Listo extends Resources {
+    /** The signature helpers without a client, for a receiver that holds no API key. */
+    static readonly webhooks: WebhookVerifier;
+    readonly webhooks: ListoWebhooks;
+    /** `"live"` or `"test"`, read from the key's prefix. */
+    readonly mode: "live" | "test";
+    readonly baseUrl: string;
+    constructor(options: ListoOptions);
+}

package/dist/client.js

@@ -0,0 +1,25 @@
+import { HttpTransport } from "./http.js";
+import { Resources, WebhooksResource } from "./resources.gen.js";
+import { constructEvent, verify, webhooks } from "./webhooks.js";
+/** `listo.webhooks`: the API's webhook calls (send a test, read delivery attempts) plus the signature helpers. */
+export class ListoWebhooks extends WebhooksResource {
+    verify(...args) {
+        return verify(...args);
+    }
+    constructEvent(...args) {
+        return constructEvent(...args);
+    }
+}
+export class Listo extends Resources {
+    /** The signature helpers without a client, for a receiver that holds no API key. */
+    static webhooks = webhooks;
+    /** `"live"` or `"test"`, read from the key's prefix. */
+    mode;
+    baseUrl;
+    constructor(options) {
+        const transport = new HttpTransport(options);
+        super(transport, { webhooks: new ListoWebhooks(transport) });
+        this.mode = transport.mode;
+        this.baseUrl = transport.baseUrl;
+    }
+}

package/dist/errors.d.ts

@@ -0,0 +1,43 @@
+export interface ListoErrorFields {
+    code: string;
+    message: string;
+    param: string | null;
+    retryable: boolean;
+    status: number | null;
+    requestId: string | null;
+    docUrl: string | null;
+    body: unknown;
+}
+export declare class ListoError extends Error {
+    /** The stable name of what went wrong (`validation_failed`, `insufficient_balance`, ...). */
+    readonly code: string;
+    /** The request field the refusal is about, when one applies. */
+    readonly param: string | null;
+    /** Whether sending the identical request again could succeed. */
+    readonly retryable: boolean;
+    /** The HTTP status, or null when no response arrived. */
+    readonly status: number | null;
+    readonly requestId: string | null;
+    readonly docUrl: string | null;
+    /** The parsed response body (or its text when it was not JSON). */
+    readonly body: unknown;
+    constructor(fields: ListoErrorFields, options?: {
+        cause?: unknown;
+    });
+}
+/** DNS failure, refused connection or timeout: no answer arrived. A write may have happened. */
+export declare class ListoConnectionError extends ListoError {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+/** A webhook whose signature did not verify. A `ListoError` with code `invalid_signature`, as in Python and Ruby. */
+export declare class ListoSignatureError extends ListoError {
+    constructor(message?: string);
+}
+/** A signed webhook body that is not a JSON object. Code `invalid_payload`, as in Python and Ruby. */
+export declare function invalidPayload(message: string, options?: {
+    cause?: unknown;
+}): ListoError;
+/** Builds the error for a non-2xx answer from its parsed body (or text). */
+export declare function errorFromResponse(status: number, requestIdHeader: string | null, body: unknown): ListoError;

package/dist/errors.js

@@ -0,0 +1,95 @@
+// One error class for everything the API refuses, so a caller writes a single
+// `catch (e) { if (e instanceof ListoError) ... }`. Branch on `code`, never on
+// `message`, which is for a person reading a log.
+const RETRYABLE_STATUSES = new Set([429, 502, 503, 504]);
+export class ListoError extends Error {
+    /** The stable name of what went wrong (`validation_failed`, `insufficient_balance`, ...). */
+    code;
+    /** The request field the refusal is about, when one applies. */
+    param;
+    /** Whether sending the identical request again could succeed. */
+    retryable;
+    /** The HTTP status, or null when no response arrived. */
+    status;
+    requestId;
+    docUrl;
+    /** The parsed response body (or its text when it was not JSON). */
+    body;
+    constructor(fields, options) {
+        super(fields.message, options);
+        this.name = "ListoError";
+        this.code = fields.code;
+        this.param = fields.param;
+        this.retryable = fields.retryable;
+        this.status = fields.status;
+        this.requestId = fields.requestId;
+        this.docUrl = fields.docUrl;
+        this.body = fields.body;
+    }
+}
+/** DNS failure, refused connection or timeout: no answer arrived. A write may have happened. */
+export class ListoConnectionError extends ListoError {
+    constructor(message, options) {
+        super({
+            code: "connection_error",
+            message,
+            param: null,
+            retryable: false,
+            status: null,
+            requestId: null,
+            docUrl: null,
+            body: null,
+        }, options);
+        this.name = "ListoConnectionError";
+    }
+}
+/** A webhook whose signature did not verify. A `ListoError` with code `invalid_signature`, as in Python and Ruby. */
+export class ListoSignatureError extends ListoError {
+    constructor(message = "The webhook signature is not valid.") {
+        super({
+            code: "invalid_signature",
+            message,
+            param: null,
+            retryable: false,
+            status: null,
+            requestId: null,
+            docUrl: null,
+            body: null,
+        });
+        this.name = "ListoSignatureError";
+    }
+}
+/** A signed webhook body that is not a JSON object. Code `invalid_payload`, as in Python and Ruby. */
+export function invalidPayload(message, options) {
+    return new ListoError({ code: "invalid_payload", message, param: null, retryable: false, status: null, requestId: null, docUrl: null, body: null }, options);
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** Builds the error for a non-2xx answer from its parsed body (or text). */
+export function errorFromResponse(status, requestIdHeader, body) {
+    const envelope = isRecord(body) && isRecord(body.error) ? body.error : null;
+    if (envelope !== null && typeof envelope.code === "string") {
+        return new ListoError({
+            code: envelope.code,
+            message: typeof envelope.message === "string" ? envelope.message : `The API answered ${status}.`,
+            param: typeof envelope.param === "string" ? envelope.param : null,
+            retryable: typeof envelope.retryable === "boolean" ? envelope.retryable : RETRYABLE_STATUSES.has(status),
+            status,
+            requestId: typeof envelope.request_id === "string" ? envelope.request_id : requestIdHeader,
+            docUrl: typeof envelope.doc_url === "string" ? envelope.doc_url : null,
+            body,
+        });
+    }
+    // An HTML page from a proxy, or JSON of another shape.
+    return new ListoError({
+        code: `http_${status}`,
+        message: `Unexpected response with status ${status}`,
+        param: null,
+        retryable: RETRYABLE_STATUSES.has(status),
+        status,
+        requestId: requestIdHeader,
+        docUrl: null,
+        body,
+    });
+}

package/dist/generated/client/client.gen.d.ts

@@ -0,0 +1,2 @@
+import type { Client, Config } from './types.gen.ts';
+export declare const createClient: (config?: Config) => Client;

package/dist/generated/client/client.gen.js

@@ -0,0 +1,216 @@
+// This file is auto-generated by @hey-api/openapi-ts
+import { createSseClient } from "../core/serverSentEvents.gen.js";
+import { getValidRequestBody } from "../core/utils.gen.js";
+import { buildUrl, createConfig, createInterceptors, getParseAs, mergeConfigs, mergeHeaders, setAuthParams, } from "./utils.gen.js";
+export const createClient = (config = {}) => {
+    let _config = mergeConfigs(createConfig(), config);
+    const getConfig = () => ({ ..._config });
+    const setConfig = (config) => {
+        _config = mergeConfigs(_config, config);
+        return getConfig();
+    };
+    const interceptors = createInterceptors();
+    const beforeRequest = async (options) => {
+        const opts = {
+            ..._config,
+            ...options,
+            fetch: options.fetch ?? _config.fetch ?? globalThis.fetch,
+            headers: mergeHeaders(_config.headers, options.headers),
+            serializedBody: undefined,
+        };
+        if (opts.security) {
+            await setAuthParams(opts);
+        }
+        if (opts.requestValidator) {
+            await opts.requestValidator(opts);
+        }
+        if (opts.body !== undefined && opts.bodySerializer) {
+            opts.serializedBody = opts.bodySerializer(opts.body);
+        }
+        // remove Content-Type header if body is empty to avoid sending invalid requests
+        if (opts.body === undefined || opts.serializedBody === '') {
+            opts.headers.delete('Content-Type');
+        }
+        const resolvedOpts = opts;
+        const url = buildUrl(resolvedOpts);
+        return { opts: resolvedOpts, url };
+    };
+    const request = async (options) => {
+        const throwOnError = options.throwOnError ?? _config.throwOnError;
+        const responseStyle = options.responseStyle ?? _config.responseStyle;
+        let request;
+        let response;
+        try {
+            const { opts, url } = await beforeRequest(options);
+            const requestInit = {
+                redirect: 'follow',
+                ...opts,
+                body: getValidRequestBody(opts),
+            };
+            request = new Request(url, requestInit);
+            for (const fn of interceptors.request.fns) {
+                if (fn) {
+                    request = await fn(request, opts);
+                }
+            }
+            // fetch must be assigned here, otherwise it would throw the error:
+            // TypeError: Failed to execute 'fetch' on 'Window': Illegal invocation
+            const _fetch = opts.fetch;
+            response = await _fetch(request);
+            for (const fn of interceptors.response.fns) {
+                if (fn) {
+                    response = await fn(response, request, opts);
+                }
+            }
+            const result = {
+                request,
+                response,
+            };
+            if (response.ok) {
+                const parseAs = (opts.parseAs === 'auto'
+                    ? getParseAs(response.headers.get('Content-Type'))
+                    : opts.parseAs) ?? 'json';
+                if (response.status === 204 || response.headers.get('Content-Length') === '0') {
+                    let emptyData;
+                    switch (parseAs) {
+                        case 'arrayBuffer':
+                        case 'blob':
+                        case 'text':
+                            emptyData = await response[parseAs]();
+                            break;
+                        case 'formData':
+                            emptyData = new FormData();
+                            break;
+                        case 'stream':
+                            emptyData = response.body;
+                            break;
+                        case 'json':
+                        default:
+                            emptyData = {};
+                            break;
+                    }
+                    return opts.responseStyle === 'data'
+                        ? emptyData
+                        : {
+                            data: emptyData,
+                            ...result,
+                        };
+                }
+                let data;
+                switch (parseAs) {
+                    case 'arrayBuffer':
+                    case 'blob':
+                    case 'formData':
+                    case 'text':
+                        data = await response[parseAs]();
+                        break;
+                    case 'json': {
+                        // Some servers return 200 with no Content-Length and empty body.
+                        // response.json() would throw; read as text and parse if non-empty.
+                        const text = await response.text();
+                        data = text ? JSON.parse(text) : {};
+                        break;
+                    }
+                    case 'stream':
+                        return opts.responseStyle === 'data'
+                            ? response.body
+                            : {
+                                data: response.body,
+                                ...result,
+                            };
+                }
+                if (parseAs === 'json') {
+                    if (opts.responseValidator) {
+                        await opts.responseValidator(data);
+                    }
+                    if (opts.responseTransformer) {
+                        data = await opts.responseTransformer(data);
+                    }
+                }
+                return opts.responseStyle === 'data'
+                    ? data
+                    : {
+                        data,
+                        ...result,
+                    };
+            }
+            const textError = await response.text();
+            let jsonError;
+            try {
+                jsonError = JSON.parse(textError);
+            }
+            catch {
+                // noop
+            }
+            throw jsonError ?? textError;
+        }
+        catch (error) {
+            let finalError = error;
+            for (const fn of interceptors.error.fns) {
+                if (fn) {
+                    finalError = await fn(finalError, response, request, options);
+                }
+            }
+            finalError = finalError || {};
+            if (throwOnError) {
+                throw finalError;
+            }
+            // TODO: we probably want to return error and improve types
+            return responseStyle === 'data'
+                ? undefined
+                : {
+                    error: finalError,
+                    request,
+                    response,
+                };
+        }
+    };
+    const makeMethodFn = (method) => (options) => request({ ...options, method });
+    const makeSseFn = (method) => async (options) => {
+        const { opts, url } = await beforeRequest(options);
+        return createSseClient({
+            ...opts,
+            body: opts.body,
+            method,
+            onRequest: async (url, init) => {
+                let request = new Request(url, init);
+                for (const fn of interceptors.request.fns) {
+                    if (fn) {
+                        request = await fn(request, opts);
+                    }
+                }
+                return request;
+            },
+            serializedBody: getValidRequestBody(opts),
+            url,
+        });
+    };
+    const _buildUrl = (options) => buildUrl({ ..._config, ...options });
+    return {
+        buildUrl: _buildUrl,
+        connect: makeMethodFn('CONNECT'),
+        delete: makeMethodFn('DELETE'),
+        get: makeMethodFn('GET'),
+        getConfig,
+        head: makeMethodFn('HEAD'),
+        interceptors,
+        options: makeMethodFn('OPTIONS'),
+        patch: makeMethodFn('PATCH'),
+        post: makeMethodFn('POST'),
+        put: makeMethodFn('PUT'),
+        request,
+        setConfig,
+        sse: {
+            connect: makeSseFn('CONNECT'),
+            delete: makeSseFn('DELETE'),
+            get: makeSseFn('GET'),
+            head: makeSseFn('HEAD'),
+            options: makeSseFn('OPTIONS'),
+            patch: makeSseFn('PATCH'),
+            post: makeSseFn('POST'),
+            put: makeSseFn('PUT'),
+            trace: makeSseFn('TRACE'),
+        },
+        trace: makeMethodFn('TRACE'),
+    };
+};

package/dist/generated/client/index.d.ts

@@ -0,0 +1,10 @@
+export type { Auth } from '../core/auth.gen.ts';
+export type { QuerySerializerOptions } from '../core/bodySerializer.gen.ts';
+export { formDataBodySerializer, jsonBodySerializer, urlSearchParamsBodySerializer, } from '../core/bodySerializer.gen.ts';
+export { buildClientParams } from '../core/params.gen.ts';
+export { serializeQueryKeyValue } from '../core/queryKeySerializer.gen.ts';
+export type { ServerSentEventsResult } from '../core/serverSentEvents.gen.ts';
+export type { ClientMeta } from '../core/types.gen.ts';
+export { createClient } from './client.gen.ts';
+export type { Client, ClientOptions, Config, CreateClientConfig, Options, RequestOptions, RequestResult, ResolvedRequestOptions, ResponseStyle, TDataShape, } from './types.gen.ts';
+export { createConfig, mergeHeaders } from './utils.gen.ts';

package/dist/generated/client/index.js

@@ -0,0 +1,6 @@
+// This file is auto-generated by @hey-api/openapi-ts
+export { formDataBodySerializer, jsonBodySerializer, urlSearchParamsBodySerializer, } from "../core/bodySerializer.gen.js";
+export { buildClientParams } from "../core/params.gen.js";
+export { serializeQueryKeyValue } from "../core/queryKeySerializer.gen.js";
+export { createClient } from "./client.gen.js";
+export { createConfig, mergeHeaders } from "./utils.gen.js";