@basetime/a2w-api-ts/dist/http/QueryBuilder.d.ts

Client library that communicates with the addtowallet API.

/**
 * Resolves the runtime prefix prepended to every URL produced by a
 * {@link QueryBuilder}. Used to swap between "relative path" mode (returns `''`) and
 * "site root" mode (returns the requester's current site base URL) at request time so
 * a later `setBaseUrl(...)` is picked up.
 */
export type PrefixResolver = () => string;
/**
 * A chainable URL builder returned by {@link QueryBuilder.create}.
 *
 * Holds a path template that may contain `{name}` placeholders, plus a bag of placeholder
 * values and an ordered list of query parameters. Call {@link toString} to interpolate the
 * placeholders (URL-encoded) and append the query string.
 *
 * Instances are mutable; the fluent methods return `this` so calls can be chained.
 */
export declare class UrlBuilder {
    private template;
    private resolvePrefix?;
    /**
     * Values for `{name}` placeholders in the path template, set via {@link addParam}.
     */
    private params;
    /**
     * Ordered list of query parameters set via {@link addQuery}. Order is preserved and
     * duplicate keys are permitted so callers can build `key=a&key=b` style strings.
     */
    private queries;
    /**
     * Constructor.
     *
     * @param template The raw path template, e.g. `/campaigns/{id}/passes`. Anything between
     *   `{` and `}` is treated as a placeholder name that must be supplied via {@link addParam}
     *   before {@link toString} is called.
     * @param resolvePrefix Optional resolver returning a prefix prepended at
     *   {@link toString} time. Used by site-root endpoints to inject the requester's
     *   current site base URL lazily.
     */
    constructor(template: string, resolvePrefix?: PrefixResolver | undefined);
    /**
     * Records a value for a `{name}` placeholder in the path template.
     *
     * Values are coerced to string and URL-encoded at {@link toString} time, not now, so
     * later overrides win.
     *
     * @param key The placeholder name (without braces).
     * @param value The value to substitute.
     */
    addParam: (key: string, value: string | number | boolean) => this;
    /**
     * Appends a query parameter.
     *
     * Order of calls is preserved in the generated query string. Duplicate keys are allowed
     * and emitted as repeated `key=value` pairs.
     *
     * @param key The query parameter name.
     * @param value The query parameter value.
     */
    addQuery: (key: string, value: string | number | boolean) => this;
    /**
     * Renders the final URL.
     *
     * Replaces every `{name}` placeholder with its URL-encoded value, prepends the lazy
     * prefix when one was supplied, and appends the collected query parameters as a
     * `?k=v&...` suffix when any are present.
     *
     * @throws Error If the template references a placeholder that was never supplied via
     *   {@link addParam}.
     */
    toString: () => string;
}
/**
 * A per-endpoint factory that produces {@link UrlBuilder} instances rooted at a common
 * base URL plus endpoint path.
 *
 * Inside the SDK this is constructed by {@link Endpoint} with an empty `baseUrl` so that
 * {@link UrlBuilder.toString} returns a relative path; the parent `HttpRequester` then
 * prepends the configured API origin. Site-root endpoints pass a lazy resolver instead
 * so the site base URL is injected at request time and a later `setBaseUrl(...)` is
 * picked up.
 */
export declare class QueryBuilder {
    private baseUrl;
    private endpointPath;
    private resolvePrefix?;
    /**
     * Constructor.
     *
     * @param baseUrl The static base URL prepended to every produced URL. Pass `''` to
     *   produce a relative path (the default mode used by the SDK's `Endpoint` base class).
     * @param endpointPath The endpoint path appended after the base URL, e.g. `/campaigns`.
     * @param resolvePrefix Optional resolver returning a prefix prepended at
     *   `UrlBuilder.toString()` time. When supplied, the resolver overrides the static
     *   `baseUrl` for prefixing purposes.
     */
    constructor(baseUrl: string, endpointPath: string, resolvePrefix?: PrefixResolver | undefined);
    /**
     * Creates a new {@link UrlBuilder} for a path under the endpoint.
     *
     * The supplied `path` is appended verbatim to `${baseUrl}${endpointPath}` and may
     * contain `{name}` placeholders that are filled in via {@link UrlBuilder.addParam}.
     *
     * @param path The path fragment beneath the endpoint root, e.g. `/{id}/passes`. Defaults
     *   to an empty string, which targets the endpoint root itself.
     */
    create: (path?: string) => UrlBuilder;
}