@persistmemory/sdk 0.1.0

package/dist/errors.d.ts

@@ -0,0 +1,159 @@
+/**
+ * What went wrong, in a shape a caller can branch on.
+ *
+ * One class per thing a caller can DO about it, which is not the same as one
+ * class per status code. `RateLimited` says wait, `Validation` says fix the
+ * request, `NotFound` says the id is wrong or gone, `Conflict` says re-read
+ * and try again. A code nobody branches on is a string that only looks like an
+ * API, so 402 and 418 and anything else unmapped land on the base class rather
+ * than growing a name each.
+ *
+ * The API's own error envelope is
+ *
+ *   { error: { code, message, fields?, requestId } }
+ *
+ * and `code` is the stable part. Branch on the class or on `code`, never on
+ * `message`: messages get rewritten for clarity, translated, and deliberately
+ * made vaguer for security, and a client keyed to message text breaks silently
+ * when any of that happens.
+ *
+ * NOTHING in here ever holds the API key. Errors are logged, serialised into
+ * bug reports and posted into issue trackers, which is exactly how a
+ * credential escapes - see `redact` at the bottom of this file, which every
+ * message this module builds passes through.
+ */
+/** The stable codes the API returns. Unknown strings are possible; see below. */
+export type ErrorCode = "VALIDATION_ERROR" | "UNAUTHORIZED" | "FORBIDDEN" | "NOT_FOUND" | "CONFLICT" | "IDEMPOTENCY_MISMATCH" | "RATE_LIMITED" | "PAYLOAD_TOO_LARGE" | "DEPENDENCY_UNAVAILABLE" | "PROCESSING_FAILED" | "INTERNAL_ERROR" | (string & {});
+export interface ApiErrorInit {
+    readonly status: number;
+    readonly code: ErrorCode;
+    readonly message: string;
+    /** Which fields were rejected, for a validation failure. */
+    readonly fields?: Readonly<Record<string, string>>;
+    /** Ties this failure to the server's log lines. Quote it in support. */
+    readonly requestId?: string;
+    /** Seconds the server asked us to wait, when it said. */
+    readonly retryAfterSeconds?: number;
+}
+/**
+ * The base every failure from this SDK inherits from.
+ *
+ * `retryable` is the single question the request loop asks. It lives on the
+ * error rather than in a table beside it because the two drift: a table says
+ * 429 is retryable while the error that reaches the loop is a transport
+ * failure nobody thought to add.
+ */
+export declare class PersistMemoryError extends Error {
+    readonly status: number;
+    readonly code: ErrorCode;
+    readonly fields?: Readonly<Record<string, string>>;
+    readonly requestId?: string;
+    readonly retryAfterSeconds?: number;
+    /** Retrying this exact request could plausibly succeed. */
+    readonly retryable: boolean;
+    constructor(init: ApiErrorInit);
+    /**
+     * A one-line summary safe to log.
+     *
+     * Provided so callers reach for this instead of `JSON.stringify(error)`,
+     * which walks own properties and would pick up anything a future field
+     * holds. Everything here is already server-supplied and key-free.
+     */
+    toString(): string;
+}
+/** 401. The key is missing, malformed, revoked, or the session expired. */
+export declare class AuthenticationError extends PersistMemoryError {
+}
+/**
+ * 403. Known caller, and this credential will never be enough.
+ *
+ * Distinct from `AuthenticationError` because the fix is different: 401 means
+ * present a credential, 403 means this key's scopes are wrong and no amount of
+ * retrying or re-signing will change it. A read-only key calling `remember`
+ * lands here.
+ */
+export declare class PermissionDeniedError extends PersistMemoryError {
+}
+/** 404. Does not exist, or is not yours - the API answers both the same way. */
+export declare class NotFoundError extends PersistMemoryError {
+}
+/** 400 and 422. The request was wrong; `fields` says where. */
+export declare class ValidationError extends PersistMemoryError {
+}
+/** 409. Something changed underneath. Re-read, then try again. */
+export declare class ConflictError extends PersistMemoryError {
+}
+/**
+ * 429. Slow down.
+ *
+ * `retryAfterSeconds` comes from the `Retry-After` header, which the API
+ * always sets on a 429. It is not advice - it is the only number that knows
+ * when the window resets, and computing our own backoff instead means being
+ * refused again and spending an attempt to learn what we were already told.
+ */
+export declare class RateLimitError extends PersistMemoryError {
+    readonly retryable = true;
+}
+/**
+ * 5xx. Ours, not yours.
+ *
+ * Retryable, because a 500 or a 503 is usually a dependency that has fallen
+ * over and will come back - and the alternative, giving up on the first one,
+ * turns a three-second blip into a failed job. Retryable does not mean
+ * REPEATED: a POST still needs an idempotency key before this client will send
+ * it again, because a 500 may have been raised after the work was done.
+ */
+export declare class ServerError extends PersistMemoryError {
+    readonly retryable = true;
+}
+/**
+ * The request never got an answer: DNS, connect, reset, or a body that died
+ * mid-stream.
+ *
+ * Status 0, because there was no status. Retryable in general - but see
+ * `isRetryable` in `client.ts`, which refuses to retry a POST that may already
+ * have been processed, since a connection dying after the server accepted the
+ * request looks identical from here.
+ */
+export declare class ConnectionError extends PersistMemoryError {
+    readonly retryable = true;
+    constructor(message: string);
+}
+/** The deadline passed. A distinct class because the fix is often a bigger one. */
+export declare class TimeoutError extends PersistMemoryError {
+    readonly retryable = true;
+    constructor(message: string);
+}
+/**
+ * The caller's own AbortSignal fired.
+ *
+ * NOT retryable, and not a timeout: someone asked for this to stop, and
+ * retrying it is the one thing they have said they do not want.
+ */
+export declare class AbortError extends PersistMemoryError {
+    constructor(message?: string);
+}
+/**
+ * A response the server refused, turned into the right class.
+ *
+ * Keyed on the CODE first and the status second. The code is the API's own
+ * vocabulary and is the more precise of the two - `IDEMPOTENCY_MISMATCH` is a
+ * 422 that means "you reused a key with a different body", which is a
+ * validation problem and not a generic unprocessable entity.
+ *
+ * The body is parsed defensively at every step. A 502 from a proxy in front of
+ * the API returns HTML, and an SDK that assumes JSON turns a bad gateway into
+ * an unhelpful SyntaxError thrown from inside the error handler.
+ */
+export declare function errorFromResponse(status: number, body: unknown, headers: {
+    get(name: string): string | null;
+}): PersistMemoryError;
+/**
+ * Removes anything key-shaped from a string bound for an error message.
+ *
+ * Every message this module produces goes through here, including the
+ * server's own. It should never contain a key - we never send it in a body
+ * and the API never echoes it - but "should never" is how credentials end up
+ * in issue trackers. The cost is one regex on a path that has already failed.
+ */
+export declare function redact(text: string): string;

package/dist/http.d.ts

@@ -0,0 +1,114 @@
+import type { BackoffOptions } from "./backoff.js";
+import type { QueryParams } from "./query.js";
+import { PersistMemoryError } from "./errors.js";
+/**
+ * The one place a request is made, retried, timed out and turned into an error.
+ *
+ * Every resource in this package goes through `request`. That is deliberate:
+ * an SDK where each resource calls `fetch` for itself is an SDK with six
+ * slightly different retry policies, and the differences only show up during
+ * an outage, which is the moment nobody wants to be reading six files.
+ *
+ * `fetch` is injected rather than imported. It is what makes a test of this
+ * incapable of opening a socket by accident, and it is the same reason every
+ * provider client in this repo takes one.
+ */
+export type { QueryParams, QueryValue } from "./query.js";
+export interface ClientOptions {
+    /**
+     * A `pm_live_...` API key, or a session JWT.
+     *
+     * Held privately and never returned, logged, stringified or put in an error.
+     * See `#apiKey` below and the `toJSON` next to it.
+     */
+    readonly apiKey: string;
+    readonly baseUrl?: string;
+    readonly fetch?: typeof globalThis.fetch;
+    /**
+     * Per-attempt deadline, not a budget for the whole call.
+     *
+     * Per attempt because a whole-call deadline interacts badly with backoff: a
+     * request that spent nine seconds waiting between retries would get one
+     * second to actually run, and the failure would look like a slow server.
+     */
+    readonly timeoutMs?: number;
+    /** Attempts, not retries. 3 means the original and two more. */
+    readonly maxAttempts?: number;
+    readonly backoff?: BackoffOptions;
+    /** Injected so tests do not spend real seconds asleep. */
+    readonly sleep?: (ms: number, signal?: AbortSignal) => Promise<void>;
+    /** Sent on every request, for support and for server-side triage. */
+    readonly userAgent?: string;
+}
+export interface RequestOptions {
+    /** Cancels the call. A caller's abort is never retried - they asked it to stop. */
+    readonly signal?: AbortSignal;
+    readonly timeoutMs?: number;
+    readonly maxAttempts?: number;
+    /**
+     * Makes a POST safe to retry.
+     *
+     * The API deduplicates on this header, so a retry after a timeout finds the
+     * first result rather than doing the work twice. Without one, this client
+     * will NOT retry a POST that may already have been processed - see
+     * `mayRetry`.
+     *
+     * Give it meaning: `remember:note-42`, not a fresh random value per call. A
+     * random one makes every retry a new request, which is exactly what it
+     * exists to prevent.
+     */
+    readonly idempotencyKey?: string;
+}
+interface InternalRequest {
+    readonly method: "GET" | "POST" | "PATCH" | "DELETE";
+    readonly path: string;
+    readonly query?: QueryParams;
+    readonly body?: unknown;
+    readonly options?: RequestOptions;
+}
+export declare class HttpClient {
+    #private;
+    constructor(options: ClientOptions);
+    /**
+     * What this object looks like when something serialises it.
+     *
+     * Both hooks return the same key-free shape. `toJSON` covers
+     * `JSON.stringify`, the inspect symbol covers `console.log` under Node, and
+     * between them they cover how a credential actually escapes: not through a
+     * deliberate log line, but through an object dumped into a bug report.
+     */
+    toJSON(): Record<string, unknown>;
+    get<T>(path: string, query?: QueryParams, options?: RequestOptions): Promise<T>;
+    post<T>(path: string, body?: unknown, options?: RequestOptions): Promise<T>;
+    patch<T>(path: string, body?: unknown, options?: RequestOptions): Promise<T>;
+    delete<T>(path: string, body?: unknown, options?: RequestOptions): Promise<T>;
+}
+/**
+ * Whether this failure is worth another attempt.
+ *
+ * Two questions, and both have to say yes. The first is whether the failure
+ * itself could clear - a 400 fails identically on every attempt, so retrying
+ * spends two more calls to learn the same thing. The second is whether
+ * repeating the REQUEST is safe, which is a different question and the one
+ * that gets skipped.
+ *
+ * For a POST the honest answer is that we usually cannot tell. A connection
+ * that died after the server accepted the request is indistinguishable from
+ * one that died before, so retrying `remember` on a timeout would queue the
+ * same note twice and the user would see it remembered twice. So a POST is
+ * retried only when:
+ *
+ *   an idempotency key was given   the API deduplicates on it, so the retry
+ *                                  returns the first result rather than
+ *                                  repeating the work
+ *
+ *   the status was 429             the request was refused BEFORE it was
+ *                                  processed. That is what a rate limit is,
+ *                                  and it is the one case where "already
+ *                                  succeeded" is not possible
+ *
+ * Every other retryable POST failure - a 500, a 503, a timeout, a reset - is
+ * given back to the caller, who knows whether repeating it is safe and this
+ * package does not.
+ */
+export declare function mayRetry(error: PersistMemoryError, request: InternalRequest): boolean;