@unofficialbox/box-open-sdk 0.1.0

package/dist/cjs/runtime.js

@@ -0,0 +1,304 @@
+"use strict";
+// Code generated by box-gantry (vendored from runtimes/typescript/gantryruntime/src/runtime.ts). DO NOT EDIT.
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Client = exports.Stream = exports.Response = exports.Request = exports.BoxApiError = void 0;
+exports.withHeader = withHeader;
+exports.withQuery = withQuery;
+exports.withJsonBody = withJsonBody;
+exports.withFormBody = withFormBody;
+exports.withStreamBody = withStreamBody;
+exports.withMultipartBody = withMultipartBody;
+exports.responseBytes = responseBytes;
+exports.responseStream = responseStream;
+exports.responseHeader = responseHeader;
+exports.statusCode = statusCode;
+const errors_js_1 = require("./errors.js");
+var errors_js_2 = require("./errors.js");
+Object.defineProperty(exports, "BoxApiError", { enumerable: true, get: function () { return errors_js_2.BoxApiError; } });
+__exportStar(require("./auth.js"), exports);
+/** The default base URLs for the D-106 URL classes. */
+const DEFAULT_BASE_URLS = {
+    api: 'https://api.box.com/2.0',
+    api_root: 'https://api.box.com',
+    upload: 'https://upload.box.com/api/2.0',
+    upload_session: 'https://upload.box.com/api/2.0',
+    oauth_authorize: 'https://account.box.com/api/oauth2',
+    download: 'https://api.box.com/2.0',
+};
+/** The runtime-owned HTTP request envelope, assembled by the `with*` builders
+ * before `fetch` executes it. */
+class Request {
+    method;
+    url;
+    headers = new Headers();
+    query = new URLSearchParams();
+    /** The buffered request body, if any (buffered so retries can replay it). */
+    body;
+    constructor(method, url) {
+        this.method = method;
+        this.url = url;
+    }
+}
+exports.Request = Request;
+/** The runtime-owned HTTP response envelope. The body is read fully so it can be
+ * replayed as bytes or a stream, and so retries stay safe. */
+class Response {
+    status;
+    headers;
+    bodyBytes;
+    constructor(status, headers, bodyBytes) {
+        this.status = status;
+        this.headers = headers;
+        this.bodyBytes = bodyBytes;
+    }
+}
+exports.Response = Response;
+/** A response/request body as bytes. The platform buffers it (the manifest's
+ * `Streaming` axis allows buffering) so a retried request can replay it. */
+class Stream {
+    data;
+    constructor(data) {
+        this.data = data;
+    }
+    /** An empty stream (e.g. an absent multipart file part). */
+    static empty() {
+        return new Stream(new Uint8Array(0));
+    }
+}
+exports.Stream = Stream;
+/** The runtime session: it holds the auth flow, base-URL configuration, and
+ * retry policy shared by every manager. */
+class Client {
+    auth;
+    baseUrls;
+    maxRetries;
+    constructor(auth, options = {}) {
+        this.auth = auth;
+        const maxRetries = options.maxRetries ?? 5;
+        if (!Number.isInteger(maxRetries) || maxRetries < 0) {
+            throw new RangeError('maxRetries must be a non-negative integer');
+        }
+        this.maxRetries = maxRetries;
+        this.baseUrls = { ...DEFAULT_BASE_URLS, ...(options.baseUrls ?? {}) };
+    }
+    /** The configured base URL for a D-106 class, without a trailing slash. */
+    baseUrl(name) {
+        return this.baseUrls[name] ?? '';
+    }
+    /** A valid access token for the configured auth flow. The `signal` is
+     * accepted for contract symmetry; token acquisition is a shared refresh not
+     * bound to a single request's cancellation (mirroring the Rust runtime). */
+    async accessToken(_signal) {
+        return this.auth.accessToken();
+    }
+    /** A request envelope for a method and fully built URL. */
+    newRequest(method, url) {
+        return new Request(method, url);
+    }
+    /** Execute the request with retries: exponential backoff + full jitter, a
+     * single force-refresh on 401, and Retry-After (as a floor) on 429/5xx.
+     *
+     * Retry policy follows idempotency: a 429 (rate-limited, never processed)
+     * retries for every method; a transport error or a 5xx may have already
+     * committed a write, so those retry only for idempotent methods
+     * (GET/HEAD/PUT/DELETE/…). The 401 refresh applies to every method. */
+    async fetch(request, signal) {
+        let token = await this.auth.accessToken();
+        const query = request.query.toString();
+        const url = query ? `${request.url}?${query}` : request.url;
+        const idempotent = isIdempotent(request.method);
+        let refreshed = false;
+        let lastError;
+        for (let attempt = 0; attempt <= this.maxRetries; attempt++) {
+            const headers = new Headers(request.headers);
+            headers.set('Authorization', `Bearer ${token}`);
+            // `httpResponse` is the platform `Response` (via inference — the name is
+            // shadowed by this module's `Response` class, so it is never annotated).
+            let httpResponse;
+            try {
+                httpResponse = await fetch(url, {
+                    method: request.method,
+                    headers,
+                    // A `Uint8Array` is a valid `BodyInit` at runtime; the cast bridges
+                    // the `Uint8Array<ArrayBufferLike>` vs `BufferSource` generic gap in
+                    // the DOM lib without narrowing the contract's plain-`Uint8Array` body.
+                    body: request.body,
+                    signal,
+                });
+            }
+            catch (err) {
+                // A transport error gives no response, so a non-idempotent write may
+                // already have committed — only retry idempotent methods.
+                lastError = err;
+                if (attempt === this.maxRetries || !idempotent) {
+                    break;
+                }
+                await sleep(backoff(attempt), signal);
+                continue;
+            }
+            const bodyBytes = new Uint8Array(await httpResponse.arrayBuffer());
+            const response = new Response(httpResponse.status, httpResponse.headers, bodyBytes);
+            // A single force-refresh on 401: re-acquire past the token cache so the
+            // retry doesn't just resend the same rejected token.
+            if (response.status === 401 && !refreshed) {
+                refreshed = true;
+                token = await this.auth.forceRefresh(token);
+                continue;
+            }
+            if (shouldRetry(response.status, idempotent) && attempt < this.maxRetries) {
+                await sleep(retryDelay(response, attempt), signal);
+                continue;
+            }
+            return response;
+        }
+        throw new errors_js_1.BoxApiError(`request failed after ${this.maxRetries + 1} attempts`, {
+            cause: lastError,
+        });
+    }
+}
+exports.Client = Client;
+/** The safety ceiling on any single retry sleep, so a hostile server-sent
+ * Retry-After can't stall the client indefinitely. */
+const MAX_RETRY_DELAY_MS = 30_000;
+/** HTTP's idempotent methods: safe to replay after a transport error or 5xx. */
+const IDEMPOTENT_METHODS = new Set(['GET', 'HEAD', 'PUT', 'DELETE', 'OPTIONS', 'TRACE']);
+function isIdempotent(method) {
+    return IDEMPOTENT_METHODS.has(method.toUpperCase());
+}
+/** Whether a response status warrants a retry for a request of this idempotency.
+ * A 429 (rate-limited, never processed) retries for any method; a 5xx may have
+ * committed a write, so it retries only for idempotent methods. */
+function shouldRetry(status, idempotent) {
+    return status === 429 || (status >= 500 && idempotent);
+}
+/** Full-jitter exponential backoff, capped at the max retry delay. */
+function backoff(attempt) {
+    const base = Math.min(2 ** attempt * 500, MAX_RETRY_DELAY_MS);
+    return Math.random() * base;
+}
+/** The delay before the next retry: exponential backoff, raised to a
+ * (delay-seconds) Retry-After as a floor when present, and clamped to
+ * `MAX_RETRY_DELAY_MS`. HTTP-date Retry-After values fall back to backoff (the
+ * same posture as the Rust runtime). */
+function retryDelay(response, attempt) {
+    let delay = backoff(attempt);
+    const header = response.headers.get('Retry-After');
+    if (header && /^\d+$/.test(header.trim())) {
+        delay = Math.max(delay, Number(header.trim()) * 1000);
+    }
+    return Math.min(delay, MAX_RETRY_DELAY_MS);
+}
+/** Sleep for `ms`, rejecting promptly if the signal aborts. */
+function sleep(ms, signal) {
+    return new Promise((resolve, reject) => {
+        if (signal?.aborted) {
+            reject(abortError(signal));
+            return;
+        }
+        const onAbort = () => {
+            clearTimeout(timer);
+            reject(abortError(signal));
+        };
+        const timer = setTimeout(() => {
+            signal?.removeEventListener('abort', onAbort);
+            resolve();
+        }, ms);
+        signal?.addEventListener('abort', onAbort, { once: true });
+    });
+}
+function abortError(signal) {
+    const reason = signal?.reason;
+    return reason instanceof Error
+        ? new errors_js_1.BoxApiError(`request aborted: ${reason.message}`)
+        : new errors_js_1.BoxApiError('request aborted');
+}
+/** Return the request with the header set. */
+function withHeader(request, name, value) {
+    request.headers.set(name, value);
+    return request;
+}
+/** Return the request with the query parameter appended, encoded. */
+function withQuery(request, name, value) {
+    request.query.append(name, value);
+    return request;
+}
+/** Return the request with the serialized JSON body and content type set. */
+function withJsonBody(request, body) {
+    request.headers.set('Content-Type', 'application/json');
+    request.body = body;
+    return request;
+}
+/** Return the request with an application/x-www-form-urlencoded body (the
+ * OAuth2 token endpoints). */
+function withFormBody(request, form) {
+    request.headers.set('Content-Type', 'application/x-www-form-urlencoded');
+    request.body = form;
+    return request;
+}
+/** Return the request with a streaming body (buffered, so retries can replay
+ * it — the manifest's `Streaming` axis permits buffering). */
+function withStreamBody(request, body, contentType) {
+    request.headers.set('Content-Type', contentType);
+    request.body = body.data;
+    return request;
+}
+/** Return the request with a Box-style multipart body: an `attributes` JSON
+ * part plus a file part (G-7). */
+function withMultipartBody(request, attributes, fileName, file) {
+    const boundary = `----gantryFormBoundary${Math.random().toString(36).slice(2)}`;
+    const encoder = new TextEncoder();
+    const escaped = fileName.replace(/["\r\n]/g, '_');
+    const parts = [
+        encoder.encode(`--${boundary}\r\nContent-Disposition: form-data; name="attributes"\r\n\r\n`),
+        attributes,
+        encoder.encode(`\r\n--${boundary}\r\nContent-Disposition: form-data; name="file"; filename="${escaped}"\r\n` +
+            'Content-Type: application/octet-stream\r\n\r\n'),
+        file.data,
+        encoder.encode(`\r\n--${boundary}--\r\n`),
+    ];
+    request.headers.set('Content-Type', `multipart/form-data; boundary=${boundary}`);
+    request.body = concat(parts);
+    return request;
+}
+/** Concatenate byte chunks into one buffer. */
+function concat(chunks) {
+    const total = chunks.reduce((sum, chunk) => sum + chunk.length, 0);
+    const out = new Uint8Array(total);
+    let offset = 0;
+    for (const chunk of chunks) {
+        out.set(chunk, offset);
+        offset += chunk.length;
+    }
+    return out;
+}
+/** Read the whole response body. */
+function responseBytes(response) {
+    return response.bodyBytes;
+}
+/** The response body as a stream, for binary downloads (FR-7.4). */
+function responseStream(response) {
+    return new Stream(response.bodyBytes);
+}
+/** A response header value, empty when absent (redirect Location, Retry-After
+ * surfacing). */
+function responseHeader(response, name) {
+    return response.headers.get(name) ?? '';
+}
+/** The response status code. */
+function statusCode(response) {
+    return response.status;
+}

package/dist/cjs/tokens.js

@@ -0,0 +1,121 @@
+"use strict";
+// Code generated by box-gantry (vendored from runtimes/typescript/gantryruntime/src/tokens.ts). DO NOT EDIT.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CachedToken = exports.DEFAULT_TOKEN_URL = void 0;
+exports.postTokenForm = postTokenForm;
+// The shared token machinery behind every exchange flow: the `Auth` contract,
+// the token-endpoint POST, and the single-flight access-token cache. Split out
+// so both `auth.ts` (developer token, CCG, OAuth) and `jwt.ts` (JWT server auth)
+// reuse it without either importing the other, and without leaking these
+// internals into the package's public surface.
+const errors_js_1 = require("./errors.js");
+/** Box's OAuth 2.0 token endpoint, shared by every exchange flow. */
+exports.DEFAULT_TOKEN_URL = 'https://api.box.com/oauth2/token';
+/** Refresh a cached token this long before expiry, so in-flight requests never
+ * race an expiry. */
+const REFRESH_MARGIN_MS = 60_000;
+/** A hard deadline on a token exchange, so a stalled endpoint can't leave a
+ * single-flight refresh (and every caller awaiting it) hung forever. Matches
+ * the Go runtime's 30s token HTTP client. */
+const TOKEN_TIMEOUT_MS = 30_000;
+/**
+ * Caches an access token and refreshes it — via the flow-specific `refresh` —
+ * when it is missing or within the refresh margin of expiry. Concurrent callers
+ * during a refresh share one in-flight exchange (single-flight), so a token is
+ * never fetched twice at once, and the exchange is not tied to any one caller.
+ */
+class CachedToken {
+    refresh;
+    token;
+    expiry;
+    inflight;
+    constructor(refresh, seed) {
+        this.refresh = refresh;
+        this.token = seed?.accessToken ?? '';
+        this.expiry = seed ? Date.now() + seed.ttlMs : 0;
+    }
+    async accessToken() {
+        if (this.token && this.expiry - Date.now() > REFRESH_MARGIN_MS) {
+            return this.token;
+        }
+        return this.refreshOnce();
+    }
+    async forceRefresh(stale) {
+        // Another caller may already have refreshed past the rejected token.
+        if (this.token && this.token !== stale) {
+            return this.token;
+        }
+        return this.refreshOnce();
+    }
+    /** Run the flow's refresh, sharing one in-flight exchange across callers. */
+    refreshOnce() {
+        if (!this.inflight) {
+            this.inflight = this.refresh()
+                .then((token) => {
+                this.token = token.accessToken;
+                this.expiry = Date.now() + token.ttlMs;
+                this.inflight = undefined;
+                return token.accessToken;
+            })
+                .catch((err) => {
+                this.inflight = undefined;
+                throw err;
+            });
+        }
+        return this.inflight;
+    }
+}
+exports.CachedToken = CachedToken;
+/**
+ * POST a form-encoded grant to the token endpoint and normalize the response.
+ * A transport failure and a non-2xx body both surface as a `BoxApiError`, so
+ * token acquisition never escapes the runtime's error contract. The optional
+ * `signal` cancels an explicit caller-initiated exchange (`exchangeCode`); the
+ * cached flows do not thread one, so a shared refresh is never bound to a single
+ * request's cancellation.
+ */
+async function postTokenForm(tokenUrl, form, signal) {
+    // An internal deadline independent of the caller's signal, combined with it
+    // when present. It also covers the body read, since the signal aborts an
+    // in-progress `fetch` (including body streaming). `AbortSignal.timeout` owns
+    // its own timer, so there is nothing to clear.
+    const deadline = AbortSignal.timeout(TOKEN_TIMEOUT_MS);
+    const combined = signal ? AbortSignal.any([signal, deadline]) : deadline;
+    let response;
+    let text;
+    try {
+        response = await fetch(tokenUrl, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/x-www-form-urlencoded',
+                Accept: 'application/json',
+            },
+            body: new URLSearchParams(form).toString(),
+            signal: combined,
+        });
+        text = await response.text();
+    }
+    catch (err) {
+        throw new errors_js_1.BoxApiError('token endpoint request failed', { cause: err });
+    }
+    if (!response.ok) {
+        throw new errors_js_1.BoxApiError(`token endpoint returned ${response.status}: ${text.trim()}`, {
+            status: response.status,
+        });
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        throw new errors_js_1.BoxApiError('token endpoint returned invalid JSON');
+    }
+    if (!parsed.access_token) {
+        throw new errors_js_1.BoxApiError('token endpoint returned no access_token');
+    }
+    return {
+        accessToken: parsed.access_token,
+        refreshToken: parsed.refresh_token ?? '',
+        ttlMs: (parsed.expires_in ?? 0) * 1000,
+    };
+}

package/dist/esm/auth.js

@@ -0,0 +1,105 @@
+// Code generated by box-gantry (vendored from runtimes/typescript/gantryruntime/src/auth.ts). DO NOT EDIT.
+// The `fetch`-only Box auth flows, each an `Auth` passed to the runtime
+// `Client`: `developerToken` (a fixed token), `clientCredentials` (CCG), and the
+// OAuth 2.0 authorization-code flow. They exchange credentials at Box's token
+// endpoint and cache the access token (via the shared machinery in `tokens.ts`).
+// JWT server auth lives in `jwt.ts` — the only flow that reaches beyond `fetch`.
+import { BoxApiError } from './errors.js';
+import { CachedToken, DEFAULT_TOKEN_URL, postTokenForm } from './tokens.js';
+/** Where a user is sent to grant an OAuth 2.0 app access. */
+const AUTHORIZE_URL = 'https://account.box.com/api/oauth2/authorize';
+/**
+ * The simplest flow: a fixed access token from the Box developer console. A
+ * fixed token cannot be refreshed, so `forceRefresh` returns it unchanged (a
+ * subsequent 401 then surfaces to the caller).
+ */
+export function developerToken(token) {
+    return {
+        accessToken: async () => token,
+        forceRefresh: async () => token,
+    };
+}
+/** Build a CCG `Auth`. Requires a subject: `enterpriseId` or `userId`. */
+export function clientCredentials(config) {
+    if (!config.userId && !config.enterpriseId) {
+        throw new BoxApiError('clientCredentials requires a subject: enterpriseId or userId');
+    }
+    const tokenUrl = config.tokenUrl ?? DEFAULT_TOKEN_URL;
+    // A `userId` acts as that managed user; otherwise the enterprise service
+    // account. The guard above rules out an empty subject.
+    const subject = config.userId
+        ? { type: 'user', id: config.userId }
+        : { type: 'enterprise', id: config.enterpriseId ?? '' };
+    return new CachedToken(() => postTokenForm(tokenUrl, {
+        grant_type: 'client_credentials',
+        client_id: config.clientId,
+        client_secret: config.clientSecret,
+        box_subject_type: subject.type,
+        box_subject_id: subject.id,
+    }));
+}
+/**
+ * Build the URL to redirect a user to so they can grant access. `state` is
+ * echoed back to the redirect URI for CSRF protection.
+ */
+export function authorizeUrl(config, redirectUri, state) {
+    const query = new URLSearchParams({
+        response_type: 'code',
+        client_id: config.clientId,
+        redirect_uri: redirectUri,
+        state,
+    });
+    return `${AUTHORIZE_URL}?${query.toString()}`;
+}
+/**
+ * The refresh exchange for the authorization-code flow: it swaps the current
+ * refresh token for a fresh access token and rotates the refresh token Box
+ * returns (Box invalidates the old one on each exchange), reporting each rotated
+ * token through `config.onRefresh` so a caller can persist it.
+ */
+function refreshTokenExchange(config, tokenUrl, initialRefresh) {
+    let refreshToken = initialRefresh;
+    return async () => {
+        const token = await postTokenForm(tokenUrl, {
+            grant_type: 'refresh_token',
+            refresh_token: refreshToken,
+            client_id: config.clientId,
+            client_secret: config.clientSecret,
+        });
+        if (token.refreshToken) {
+            refreshToken = token.refreshToken;
+            config.onRefresh?.(token.refreshToken);
+        }
+        return token;
+    };
+}
+/**
+ * Resume the authorization-code flow from a previously stored refresh token,
+ * exchanging it for access tokens as needed.
+ */
+export function oauth(config, refreshToken) {
+    const tokenUrl = config.tokenUrl ?? DEFAULT_TOKEN_URL;
+    return new CachedToken(refreshTokenExchange(config, tokenUrl, refreshToken));
+}
+/**
+ * Exchange an authorization code for an `Auth` that refreshes itself thereafter.
+ * The initial refresh token is reported through `config.onRefresh` so it can be
+ * persisted immediately.
+ */
+export async function exchangeCode(config, code, redirectUri, signal) {
+    const tokenUrl = config.tokenUrl ?? DEFAULT_TOKEN_URL;
+    const token = await postTokenForm(tokenUrl, {
+        grant_type: 'authorization_code',
+        code,
+        client_id: config.clientId,
+        client_secret: config.clientSecret,
+        redirect_uri: redirectUri,
+    }, signal);
+    if (!token.refreshToken) {
+        throw new BoxApiError('authorization-code exchange returned no refresh_token');
+    }
+    config.onRefresh?.(token.refreshToken);
+    // Seed the cache with the access token we just obtained, and refresh via the
+    // rotating refresh token thereafter.
+    return new CachedToken(refreshTokenExchange(config, tokenUrl, token.refreshToken), token);
+}

package/dist/esm/buildinfo.js

@@ -0,0 +1,7 @@
+// Code generated by box-gantry 0.1.0 (spec ee7d55aedefe2fa0). DO NOT EDIT.
+/** The box-gantry engine version that generated this SDK. */
+export const ENGINE = "0.1.0";
+/** Fingerprint of the input spec set. */
+export const SPEC_FINGERPRINT = "ee7d55aedefe2fa0";
+/** The target language key (FR-4). */
+export const TARGET = "typescript";