@unofficialbox/box-open-sdk 0.7.0 → 0.8.0

package/dist/esm/models/schemas/metadata_templates.js

@@ -1,2 +1,2 @@
-// Code generated by box-gantry 0.1.0 (spec 3283827dcf199770) for Box API 2024.0. DO NOT EDIT.
+// Code generated by box-gantry 0.1.0 (spec 21e020ceb5dcf964) for Box API 2024.0. DO NOT EDIT.
 export {};

package/dist/esm/models/schemas/notes.js

@@ -1,2 +1,2 @@
-// Code generated by box-gantry 0.1.0 (spec 3283827dcf199770) for Box API 2024.0. DO NOT EDIT.
+// Code generated by box-gantry 0.1.0 (spec 21e020ceb5dcf964) for Box API 2024.0. DO NOT EDIT.
 export {};

package/dist/esm/models/schemas/query.js

@@ -1,2 +1,2 @@
-// Code generated by box-gantry 0.1.0 (spec 3283827dcf199770) for Box API 2024.0. DO NOT EDIT.
+// Code generated by box-gantry 0.1.0 (spec 21e020ceb5dcf964) for Box API 2024.0. DO NOT EDIT.
 export {};

package/dist/esm/models/schemas/recent_items.js

@@ -1,2 +1,2 @@
-// Code generated by box-gantry 0.1.0 (spec 3283827dcf199770) for Box API 2024.0. DO NOT EDIT.
+// Code generated by box-gantry 0.1.0 (spec 21e020ceb5dcf964) for Box API 2024.0. DO NOT EDIT.
 export {};

package/dist/esm/models/schemas/retention_policies.js

@@ -1,2 +1,2 @@
-// Code generated by box-gantry 0.1.0 (spec 3283827dcf199770) for Box API 2024.0. DO NOT EDIT.
+// Code generated by box-gantry 0.1.0 (spec 21e020ceb5dcf964) for Box API 2024.0. DO NOT EDIT.
 export {};

package/dist/esm/models/schemas/retention_policy_assignments.js

@@ -1,2 +1,2 @@
-// Code generated by box-gantry 0.1.0 (spec 3283827dcf199770) for Box API 2024.0. DO NOT EDIT.
+// Code generated by box-gantry 0.1.0 (spec 21e020ceb5dcf964) for Box API 2024.0. DO NOT EDIT.
 export {};

package/dist/esm/models/schemas/search.js

@@ -1,2 +1,2 @@
-// Code generated by box-gantry 0.1.0 (spec 3283827dcf199770) for Box API 2024.0. DO NOT EDIT.
+// Code generated by box-gantry 0.1.0 (spec 21e020ceb5dcf964) for Box API 2024.0. DO NOT EDIT.
 export {};

package/dist/esm/models/schemas/session_termination.js

@@ -1,2 +1,2 @@
-// Code generated by box-gantry 0.1.0 (spec 3283827dcf199770) for Box API 2024.0. DO NOT EDIT.
+// Code generated by box-gantry 0.1.0 (spec 21e020ceb5dcf964) for Box API 2024.0. DO NOT EDIT.
 export {};

package/dist/esm/models/schemas/shared_links_folders.js

@@ -1,2 +1,2 @@
-// Code generated by box-gantry 0.1.0 (spec 3283827dcf199770) for Box API 2024.0. DO NOT EDIT.
+// Code generated by box-gantry 0.1.0 (spec 21e020ceb5dcf964) for Box API 2024.0. DO NOT EDIT.
 export {};

package/dist/esm/models/schemas/shield_information_barrier_reports.js

@@ -1,2 +1,2 @@
-// Code generated by box-gantry 0.1.0 (spec 3283827dcf199770) for Box API 2024.0. DO NOT EDIT.
+// Code generated by box-gantry 0.1.0 (spec 21e020ceb5dcf964) for Box API 2024.0. DO NOT EDIT.
 export {};

package/dist/esm/models/schemas/shield_information_barrier_segment_members.js

@@ -1,2 +1,2 @@
-// Code generated by box-gantry 0.1.0 (spec 3283827dcf199770) for Box API 2024.0. DO NOT EDIT.
+// Code generated by box-gantry 0.1.0 (spec 21e020ceb5dcf964) for Box API 2024.0. DO NOT EDIT.
 export {};

package/dist/esm/models/schemas/shield_information_barrier_segment_restrictions.js

@@ -1,2 +1,2 @@
-// Code generated by box-gantry 0.1.0 (spec 3283827dcf199770) for Box API 2024.0. DO NOT EDIT.
+// Code generated by box-gantry 0.1.0 (spec 21e020ceb5dcf964) for Box API 2024.0. DO NOT EDIT.
 export {};

package/dist/esm/models/schemas/shield_information_barrier_segments.js

@@ -1,2 +1,2 @@
-// Code generated by box-gantry 0.1.0 (spec 3283827dcf199770) for Box API 2024.0. DO NOT EDIT.
+// Code generated by box-gantry 0.1.0 (spec 21e020ceb5dcf964) for Box API 2024.0. DO NOT EDIT.
 export {};

package/dist/esm/models/schemas/shield_information_barriers.js

@@ -1,2 +1,2 @@
-// Code generated by box-gantry 0.1.0 (spec 3283827dcf199770) for Box API 2024.0. DO NOT EDIT.
+// Code generated by box-gantry 0.1.0 (spec 21e020ceb5dcf964) for Box API 2024.0. DO NOT EDIT.
 export {};

package/dist/esm/models/schemas/shield_lists.js

@@ -1,2 +1,2 @@
-// Code generated by box-gantry 0.1.0 (spec 3283827dcf199770) for Box API 2024.0. DO NOT EDIT.
+// Code generated by box-gantry 0.1.0 (spec 21e020ceb5dcf964) for Box API 2024.0. DO NOT EDIT.
 export {};

package/dist/esm/models/schemas/shuttle.js

@@ -1,2 +1,2 @@
-// Code generated by box-gantry 0.1.0 (spec 3283827dcf199770) for Box API 2024.0. DO NOT EDIT.
+// Code generated by box-gantry 0.1.0 (spec 21e020ceb5dcf964) for Box API 2024.0. DO NOT EDIT.
 export {};

package/dist/esm/models/schemas/sign_requests.js

@@ -1,2 +1,2 @@
-// Code generated by box-gantry 0.1.0 (spec 3283827dcf199770) for Box API 2024.0. DO NOT EDIT.
+// Code generated by box-gantry 0.1.0 (spec 21e020ceb5dcf964) for Box API 2024.0. DO NOT EDIT.
 export {};

package/dist/esm/models/schemas/sign_templates.js

@@ -1,2 +1,2 @@
-// Code generated by box-gantry 0.1.0 (spec 3283827dcf199770) for Box API 2024.0. DO NOT EDIT.
+// Code generated by box-gantry 0.1.0 (spec 21e020ceb5dcf964) for Box API 2024.0. DO NOT EDIT.
 export {};

package/dist/esm/models/schemas/skills.js

@@ -1,2 +1,2 @@
-// Code generated by box-gantry 0.1.0 (spec 3283827dcf199770) for Box API 2024.0. DO NOT EDIT.
+// Code generated by box-gantry 0.1.0 (spec 21e020ceb5dcf964) for Box API 2024.0. DO NOT EDIT.
 export {};

package/dist/esm/models/schemas/storage_policies.js

@@ -1,2 +1,2 @@
-// Code generated by box-gantry 0.1.0 (spec 3283827dcf199770) for Box API 2024.0. DO NOT EDIT.
+// Code generated by box-gantry 0.1.0 (spec 21e020ceb5dcf964) for Box API 2024.0. DO NOT EDIT.
 export {};

package/dist/esm/models/schemas/storage_policy_assignments.js

@@ -1,2 +1,2 @@
-// Code generated by box-gantry 0.1.0 (spec 3283827dcf199770) for Box API 2024.0. DO NOT EDIT.
+// Code generated by box-gantry 0.1.0 (spec 21e020ceb5dcf964) for Box API 2024.0. DO NOT EDIT.
 export {};

package/dist/esm/models/schemas/task_assignments.js

@@ -1,2 +1,2 @@
-// Code generated by box-gantry 0.1.0 (spec 3283827dcf199770) for Box API 2024.0. DO NOT EDIT.
+// Code generated by box-gantry 0.1.0 (spec 21e020ceb5dcf964) for Box API 2024.0. DO NOT EDIT.
 export {};

package/dist/esm/models/schemas/tasks.js

@@ -1,2 +1,2 @@
-// Code generated by box-gantry 0.1.0 (spec 3283827dcf199770) for Box API 2024.0. DO NOT EDIT.
+// Code generated by box-gantry 0.1.0 (spec 21e020ceb5dcf964) for Box API 2024.0. DO NOT EDIT.
 export {};

package/dist/esm/models/schemas/terms_of_service_user_statuses.js

@@ -1,2 +1,2 @@
-// Code generated by box-gantry 0.1.0 (spec 3283827dcf199770) for Box API 2024.0. DO NOT EDIT.
+// Code generated by box-gantry 0.1.0 (spec 21e020ceb5dcf964) for Box API 2024.0. DO NOT EDIT.
 export {};

package/dist/esm/models/schemas/terms_of_services.js

@@ -1,2 +1,2 @@
-// Code generated by box-gantry 0.1.0 (spec 3283827dcf199770) for Box API 2024.0. DO NOT EDIT.
+// Code generated by box-gantry 0.1.0 (spec 21e020ceb5dcf964) for Box API 2024.0. DO NOT EDIT.
 export {};

package/dist/esm/models/schemas/transfer.js

@@ -1,2 +1,2 @@
-// Code generated by box-gantry 0.1.0 (spec 3283827dcf199770) for Box API 2024.0. DO NOT EDIT.
+// Code generated by box-gantry 0.1.0 (spec 21e020ceb5dcf964) for Box API 2024.0. DO NOT EDIT.
 export {};

package/dist/esm/models/schemas/trashed_files.js

@@ -1,2 +1,2 @@
-// Code generated by box-gantry 0.1.0 (spec 3283827dcf199770) for Box API 2024.0. DO NOT EDIT.
+// Code generated by box-gantry 0.1.0 (spec 21e020ceb5dcf964) for Box API 2024.0. DO NOT EDIT.
 export {};

package/dist/esm/models/schemas/trashed_folders.js

@@ -1,2 +1,2 @@
-// Code generated by box-gantry 0.1.0 (spec 3283827dcf199770) for Box API 2024.0. DO NOT EDIT.
+// Code generated by box-gantry 0.1.0 (spec 21e020ceb5dcf964) for Box API 2024.0. DO NOT EDIT.
 export {};

package/dist/esm/models/schemas/trashed_items.js

@@ -1,2 +1,2 @@
-// Code generated by box-gantry 0.1.0 (spec 3283827dcf199770) for Box API 2024.0. DO NOT EDIT.
+// Code generated by box-gantry 0.1.0 (spec 21e020ceb5dcf964) for Box API 2024.0. DO NOT EDIT.
 export {};

package/dist/esm/models/schemas/trashed_web_links.js

@@ -1,2 +1,2 @@
-// Code generated by box-gantry 0.1.0 (spec 3283827dcf199770) for Box API 2024.0. DO NOT EDIT.
+// Code generated by box-gantry 0.1.0 (spec 21e020ceb5dcf964) for Box API 2024.0. DO NOT EDIT.
 export {};

package/dist/esm/models/schemas/uploads.js

@@ -1,2 +1,2 @@
-// Code generated by box-gantry 0.1.0 (spec 3283827dcf199770) for Box API 2024.0. DO NOT EDIT.
+// Code generated by box-gantry 0.1.0 (spec 21e020ceb5dcf964) for Box API 2024.0. DO NOT EDIT.
 export {};

package/dist/esm/models/schemas/user_collaborations.js

@@ -1,2 +1,2 @@
-// Code generated by box-gantry 0.1.0 (spec 3283827dcf199770) for Box API 2024.0. DO NOT EDIT.
+// Code generated by box-gantry 0.1.0 (spec 21e020ceb5dcf964) for Box API 2024.0. DO NOT EDIT.
 export {};

package/dist/esm/models/schemas/users.js

@@ -1,2 +1,2 @@
-// Code generated by box-gantry 0.1.0 (spec 3283827dcf199770) for Box API 2024.0. DO NOT EDIT.
+// Code generated by box-gantry 0.1.0 (spec 21e020ceb5dcf964) for Box API 2024.0. DO NOT EDIT.
 export {};

package/dist/esm/models/schemas/web_links.js

@@ -1,2 +1,2 @@
-// Code generated by box-gantry 0.1.0 (spec 3283827dcf199770) for Box API 2024.0. DO NOT EDIT.
+// Code generated by box-gantry 0.1.0 (spec 21e020ceb5dcf964) for Box API 2024.0. DO NOT EDIT.
 export {};

package/dist/esm/models/schemas/webhooks.js

@@ -1,2 +1,2 @@
-// Code generated by box-gantry 0.1.0 (spec 3283827dcf199770) for Box API 2024.0. DO NOT EDIT.
+// Code generated by box-gantry 0.1.0 (spec 21e020ceb5dcf964) for Box API 2024.0. DO NOT EDIT.
 export {};

package/dist/esm/models/schemas/workflows.js

@@ -1,2 +1,2 @@
-// Code generated by box-gantry 0.1.0 (spec 3283827dcf199770) for Box API 2024.0. DO NOT EDIT.
+// Code generated by box-gantry 0.1.0 (spec 21e020ceb5dcf964) for Box API 2024.0. DO NOT EDIT.
 export {};

package/dist/esm/models/schemas/zip_downloads.js

@@ -1,2 +1,2 @@
-// Code generated by box-gantry 0.1.0 (spec 3283827dcf199770) for Box API 2024.0. DO NOT EDIT.
+// Code generated by box-gantry 0.1.0 (spec 21e020ceb5dcf964) for Box API 2024.0. DO NOT EDIT.
 export {};

package/dist/esm/models/schemas.js

@@ -1,4 +1,4 @@
-// Code generated by box-gantry 0.1.0 (spec 3283827dcf199770) for Box API 2024.0. DO NOT EDIT.
+// Code generated by box-gantry 0.1.0 (spec 21e020ceb5dcf964) for Box API 2024.0. DO NOT EDIT.
 export * from './schemas/ai.js';
 export * from './schemas/ai_studio.js';
 export * from './schemas/app_item_associations.js';

package/dist/esm/runtime.js

@@ -1,7 +1,8 @@
 // Code generated by box-gantry (vendored from runtimes/typescript/gantryruntime/src/runtime.ts). DO NOT EDIT.
 import { BoxApiError, apiErrorFromResponse } from './errors.js';
-export { BoxApiError } from './errors.js';
+export { BoxApiError, isPreconditionFailed } from './errors.js';
 export * from './auth.js';
+export * from './webhooks.js';
 /** The default base URLs for the D-106 URL classes. */
 const DEFAULT_BASE_URLS = {
     api: 'https://api.box.com/2.0',
@@ -284,3 +285,112 @@ export function responseHeader(response, name) {
 export function statusCode(response) {
     return response.status;
 }
+const DEFAULT_LONG_POLL_RETRIES = 10;
+const DEFAULT_LONG_POLL_TIMEOUT_SECONDS = 610;
+/** Box may deliver an event twice; this many recent event ids are kept to drop
+ * the repeats (the bound Box's own SDKs use). */
+const MAX_SEEN_EVENTS = 1000;
+/**
+ * Follow Box's long-poll protocol from `position` (`'now'` for events from
+ * here on): yield the events after it, each once, then wait on a real-time
+ * server until Box reports a change and yield those. A `reconnect` answer, or
+ * exhausting the server's retries, lists a fresh server. A long poll that times
+ * out or fails in transit is retried; an error response from Box ends the
+ * stream by throwing it, and aborting `signal` throws the abort.
+ */
+export async function* eventStream(client, position, source, signal) {
+    let seen = new Set();
+    let server;
+    let retries = 0;
+    for (;;) {
+        const { events, next } = await source.page(position);
+        for (const event of events) {
+            const id = source.id(event);
+            if (id !== undefined) {
+                if (seen.has(id)) {
+                    continue;
+                }
+                seen.add(id);
+            }
+            yield event;
+        }
+        if (seen.size >= MAX_SEEN_EVENTS) {
+            // Repeats arrive close together: keep only this page's ids.
+            seen = new Set();
+            for (const event of events) {
+                const id = source.id(event);
+                if (id !== undefined) {
+                    seen.add(id);
+                }
+            }
+        }
+        if (next !== undefined && next !== '') {
+            position = next;
+        }
+        // Wait for Box to report a change after `position`.
+        for (let changed = false; !changed;) {
+            if (server === undefined || retries >= server.maxRetries) {
+                const listed = await source.server();
+                server = {
+                    url: listed.url,
+                    maxRetries: positiveOr(listed.maxRetries, DEFAULT_LONG_POLL_RETRIES),
+                    retryTimeoutSeconds: positiveOr(listed.retryTimeoutSeconds, DEFAULT_LONG_POLL_TIMEOUT_SECONDS),
+                };
+                retries = 0;
+            }
+            retries++;
+            let message;
+            try {
+                message = await longPoll(client, server, position, signal);
+            }
+            catch (err) {
+                if (signal?.aborted || (err instanceof BoxApiError && err.status !== undefined)) {
+                    throw err;
+                }
+                // Timed out or failed in transit: poll again.
+                continue;
+            }
+            if (message === 'new_change') {
+                changed = true;
+            }
+            else if (message === 'reconnect' || message === 'max_retries') {
+                server = undefined;
+            }
+        }
+    }
+}
+function positiveOr(value, fallback) {
+    return value !== undefined && value > 0 ? value : fallback;
+}
+/** Wait on a real-time server for Box's next message about the stream after
+ * `position`: `new_change`, `reconnect`, or `max_retries`. */
+async function longPoll(client, server, position, signal) {
+    const separator = server.url.includes('?') ? '&' : '?';
+    const url = `${server.url}${separator}stream_position=${encodeURIComponent(position)}`;
+    const timeout = AbortSignal.timeout(server.retryTimeoutSeconds * 1000);
+    const response = await client.fetch(client.newRequest('GET', url), signal === undefined ? timeout : AbortSignal.any([signal, timeout]));
+    const answer = JSON.parse(new TextDecoder().decode(response.bodyBytes));
+    if (typeof answer === 'object' && answer !== null && 'message' in answer) {
+        return typeof answer.message === 'string' ? answer.message : undefined;
+    }
+    return undefined;
+}
+/** A stream position Box sent as a JSON string or number, as the string to
+ * send back. */
+export function streamPosition(value) {
+    if (typeof value === 'string') {
+        return value;
+    }
+    return typeof value === 'number' || typeof value === 'bigint' ? String(value) : undefined;
+}
+/** `JSON.parse`, except an integer too large for a `number` keeps its exact
+ * digits as a string — a stream position must round-trip unchanged. */
+export function parseJsonExact(text) {
+    const reviver = (_key, value, context) => typeof value === 'number' &&
+        !Number.isSafeInteger(value) &&
+        context?.source !== undefined &&
+        /^-?\d+$/.test(context.source)
+        ? context.source
+        : value;
+    return JSON.parse(text, reviver);
+}

package/dist/esm/webhooks.js

@@ -0,0 +1,109 @@
+// Code generated by box-gantry (vendored from runtimes/typescript/gantryruntime/src/webhooks.ts). DO NOT EDIT.
+// Box webhook signature verification (Box's v2 scheme). Each
+// `BOX-SIGNATURE-*` header of a delivery is the base64 HMAC-SHA256, under that
+// signature key, of the body followed by the `BOX-DELIVERY-TIMESTAMP` header.
+// Built on WebCrypto (`crypto.subtle`), so it runs in Node and browsers alike
+// and needs no `node:crypto`; `subtle.verify` compares in constant time.
+/** How old a delivery may be, in seconds, before it's rejected as a possible
+ * replay: Box's ten minutes. */
+export const DEFAULT_WEBHOOK_MAX_AGE_SECONDS = 600;
+/**
+ * Whether `body` and `headers` are a genuine, recent delivery from Box. Pass
+ * the body exactly as received; header names match in any case. Resolves
+ * `false` for an unknown signature version or algorithm, a delivery older than
+ * the maximum age or timestamped in the future, and a signature no configured
+ * key produces.
+ */
+export async function verifyWebhook(body, headers, keys) {
+    const header = (name) => {
+        if (headers instanceof Headers) {
+            return headers.get(name) ?? undefined;
+        }
+        for (const [key, value] of Object.entries(headers)) {
+            if (key.toLowerCase() === name) {
+                return value;
+            }
+        }
+        return undefined;
+    };
+    if (header('box-signature-version') !== '1' || header('box-signature-algorithm') !== 'HmacSHA256') {
+        return false;
+    }
+    const timestamp = header('box-delivery-timestamp');
+    const sentMs = timestamp === undefined ? NaN : Date.parse(timestamp);
+    if (Number.isNaN(sentMs)) {
+        return false;
+    }
+    // Whole seconds, as Box's own SDKs compare them.
+    const sent = Math.floor(sentMs / 1000);
+    const at = Math.floor((keys.now ?? new Date()).getTime() / 1000);
+    if (sent > at || at - sent > (keys.maxAgeSeconds ?? DEFAULT_WEBHOOK_MAX_AGE_SECONDS)) {
+        return false;
+    }
+    const encoder = new TextEncoder();
+    const raw = typeof body === 'string' ? encoder.encode(body) : Uint8Array.from(body);
+    const bodies = [raw];
+    const escaped = escapeNonAscii(raw);
+    if (escaped !== undefined) {
+        bodies.push(encoder.encode(escaped));
+    }
+    const stamp = encoder.encode(timestamp);
+    const signed = [
+        [keys.primaryKey, 'box-signature-primary'],
+        [keys.secondaryKey, 'box-signature-secondary'],
+    ];
+    for (const [key, name] of signed) {
+        const received = decodeBase64(header(name));
+        if (key === undefined || key === '' || received === undefined) {
+            continue;
+        }
+        const hmac = await crypto.subtle.importKey('raw', encoder.encode(key), { name: 'HMAC', hash: 'SHA-256' }, false, ['verify']);
+        for (const candidate of bodies) {
+            const message = new Uint8Array(candidate.length + stamp.length);
+            message.set(candidate);
+            message.set(stamp, candidate.length);
+            if (await crypto.subtle.verify('HMAC', hmac, received, message)) {
+                return true;
+            }
+        }
+    }
+    return false;
+}
+/** Standard base64 to bytes; `undefined` when absent, empty, or malformed. */
+function decodeBase64(value) {
+    if (value === undefined || value === '') {
+        return undefined;
+    }
+    try {
+        return Uint8Array.from(atob(value), (c) => c.charCodeAt(0));
+    }
+    catch {
+        return undefined;
+    }
+}
+/** `body` with every character from U+007F up written as a JSON `\uXXXX`
+ * escape (UTF-16, lowercase hex) — the form Box signs. A body re-encoded as
+ * raw UTF-8 on its way to the caller verifies through it. `undefined` when
+ * `body` is already all ASCII, or is not UTF-8. */
+function escapeNonAscii(body) {
+    let text;
+    try {
+        text = new TextDecoder('utf-8', { fatal: true }).decode(body);
+    }
+    catch {
+        return undefined;
+    }
+    let out = '';
+    let escaped = false;
+    for (let i = 0; i < text.length; i++) {
+        const unit = text.charCodeAt(i);
+        if (unit < 0x7f) {
+            out += text[i];
+        }
+        else {
+            escaped = true;
+            out += `\\u${unit.toString(16).padStart(4, '0')}`;
+        }
+    }
+    return escaped ? out : undefined;
+}

package/dist/types/buildinfo.d.ts

@@ -1,6 +1,6 @@
 /** The box-gantry engine version that generated this SDK. */
 export declare const ENGINE = "0.1.0";
 /** Fingerprint of the input spec set. */
-export declare const SPEC_FINGERPRINT = "3283827dcf199770";
+export declare const SPEC_FINGERPRINT = "21e020ceb5dcf964";
 /** The target language key (FR-4). */
 export declare const TARGET = "typescript";

package/dist/types/errors.d.ts

@@ -33,6 +33,10 @@ export declare class BoxApiError extends Error {
     readonly body?: Uint8Array;
     constructor(message: string, options?: BoxApiErrorOptions);
 }
+/** Whether `err` is Box's 412 Precondition Failed: an `If-Match` write whose
+ * etag no longer matches, because the item changed since it was read. Re-read
+ * the item and retry with its new etag. */
+export declare function isPreconditionFailed(err: unknown): err is BoxApiError;
 /** The error for a non-2xx response: `Client.fetch` throws it once the retry
  * budget and the single 401 refresh are spent, so a caller never mistakes an
  * error body for a result. Box's error fields are read from the body when it

package/dist/types/managers/events.d.ts

@@ -15,4 +15,8 @@ export declare class EventsManager {
     constructor(session: runtime.Client);
     list(opts?: EventsManagerListOptions): Promise<models.schemas.Events>;
     options(): Promise<models.schemas.RealtimeServers>;
+    /** Box's long-poll event stream from `opts.stream_position` (`'now'` when
+     * unset): yields each event once, then waits on a real-time server for the
+     * next change. It rejects when a call fails; aborting `signal` stops it. */
+    stream(opts?: EventsManagerListOptions, signal?: AbortSignal): AsyncGenerator<models.schemas.Event, void, undefined>;
 }

package/dist/types/managers/web_links.d.ts

@@ -3,6 +3,15 @@ import type * as models from '../models/index.js';
 /** Optional parameters for WebLinksManager.get. */
 export interface WebLinksManagerGetOptions {
     boxapi?: string;
+    "if-none-match"?: string;
+}
+/** Optional parameters for WebLinksManager.update. */
+export interface WebLinksManagerUpdateOptions {
+    "if-match"?: string;
+}
+/** Optional parameters for WebLinksManager.delete_. */
+export interface WebLinksManagerDeleteOptions {
+    "if-match"?: string;
 }
 /** Operations for the "web_links" API area. */
 export declare class WebLinksManager {
@@ -10,6 +19,9 @@ export declare class WebLinksManager {
     constructor(session: runtime.Client);
     create(body: models.schemas.CreateWebLinkRequest): Promise<models.schemas.WebLink>;
     get(webLinkId: string, opts?: WebLinksManagerGetOptions): Promise<models.schemas.WebLink>;
-    update(webLinkId: string, body: models.schemas.UpdateWebLinkRequest): Promise<models.schemas.WebLink>;
-    delete_(webLinkId: string): Promise<void>;
+    /** `get` with `If-None-Match` set to `etag`: resolves `undefined` when
+     * the item is unchanged since `etag` (Box answers 304 Not Modified). */
+    getIfModified(webLinkId: string, etag: string, opts?: WebLinksManagerGetOptions): Promise<models.schemas.WebLink | undefined>;
+    update(webLinkId: string, body: models.schemas.UpdateWebLinkRequest, opts?: WebLinksManagerUpdateOptions): Promise<models.schemas.WebLink>;
+    delete_(webLinkId: string, opts?: WebLinksManagerDeleteOptions): Promise<void>;
 }

package/dist/types/runtime.d.ts

@@ -1,6 +1,7 @@
 import type { Auth } from './auth.js';
-export { BoxApiError } from './errors.js';
+export { BoxApiError, isPreconditionFailed } from './errors.js';
 export * from './auth.js';
+export * from './webhooks.js';
 /** The runtime-owned HTTP request envelope, assembled by the `with*` builders
  * before `fetch` executes it. */
 export declare class Request {
@@ -97,3 +98,37 @@ export declare function responseStream(response: Response): Stream;
 export declare function responseHeader(response: Response, name: string): string;
 /** The response status code. */
 export declare function statusCode(response: Response): number;
+/** One of Box's real-time servers, as `OPTIONS /events` lists them. An absent
+ * `maxRetries` or `retryTimeoutSeconds` takes Box's documented default. */
+export interface LongPollServer {
+    url: string;
+    maxRetries?: number;
+    retryTimeoutSeconds?: number;
+}
+/** What `eventStream` drives: the typed calls a generated events manager
+ * supplies. `server` lists a real-time server; `page` fetches the events after
+ * a stream position and the position to wait from next; `id` names an event
+ * so a repeat can be dropped. */
+export interface EventSource<E> {
+    server(): Promise<LongPollServer>;
+    page(position: string): Promise<{
+        events: E[];
+        next?: string;
+    }>;
+    id(event: E): string | undefined;
+}
+/**
+ * Follow Box's long-poll protocol from `position` (`'now'` for events from
+ * here on): yield the events after it, each once, then wait on a real-time
+ * server until Box reports a change and yield those. A `reconnect` answer, or
+ * exhausting the server's retries, lists a fresh server. A long poll that times
+ * out or fails in transit is retried; an error response from Box ends the
+ * stream by throwing it, and aborting `signal` throws the abort.
+ */
+export declare function eventStream<E>(client: Client, position: string, source: EventSource<E>, signal?: AbortSignal): AsyncGenerator<E, void, undefined>;
+/** A stream position Box sent as a JSON string or number, as the string to
+ * send back. */
+export declare function streamPosition(value: unknown): string | undefined;
+/** `JSON.parse`, except an integer too large for a `number` keeps its exact
+ * digits as a string — a stream position must round-trip unchanged. */
+export declare function parseJsonExact(text: string): unknown;

package/dist/types/webhooks.d.ts

@@ -0,0 +1,24 @@
+/** How old a delivery may be, in seconds, before it's rejected as a possible
+ * replay: Box's ten minutes. */
+export declare const DEFAULT_WEBHOOK_MAX_AGE_SECONDS = 600;
+/** The keys and limits a delivery is checked against. */
+export interface WebhookKeys {
+    /** The app's primary signature key, from the Developer Console. */
+    primaryKey?: string;
+    /** The app's secondary signature key. A delivery is genuine when the
+     * signature of any configured key matches, so a key can be rotated while the
+     * other keeps verifying. */
+    secondaryKey?: string;
+    /** How old a delivery may be (default `DEFAULT_WEBHOOK_MAX_AGE_SECONDS`). */
+    maxAgeSeconds?: number;
+    /** The clock (default: now). */
+    now?: Date;
+}
+/**
+ * Whether `body` and `headers` are a genuine, recent delivery from Box. Pass
+ * the body exactly as received; header names match in any case. Resolves
+ * `false` for an unknown signature version or algorithm, a delivery older than
+ * the maximum age or timestamped in the future, and a signature no configured
+ * key produces.
+ */
+export declare function verifyWebhook(body: Uint8Array | string, headers: Headers | Record<string, string | undefined>, keys: WebhookKeys): Promise<boolean>;

package/docs/README.md

@@ -9,6 +9,7 @@ One resource manager per Box API tag, reached through the single
 - [Authentication](auth.md)
 - [Pagination](pagination.md)
 - [Errors](errors.md)
+- [Webhooks](webhooks.md)
 
 ## Managers
 

package/docs/errors.md

@@ -26,26 +26,32 @@ Files and folders carry an `etag`. Send it back to stay in sync with Box
 (Box's [Ensure consistency](https://developer.box.com/guides/api-calls/ensure-consistency/)
 guide):
 
-- **Reads** — a file or folder `get`, and each shared-item lookup, has an
+- **Reads** — a file, folder, or web link `get`, and each shared-item lookup, has an
   `…IfModified` variant that takes the stored etag, sends it as
   `If-None-Match`, and returns `undefined` when Box answers `304 Not Modified`:
   keep your cached copy. (The plain method surfaces that 304 as the error
   above if you set `if-none-match` on it yourself.)
-- **Writes** — pass the etag as `'if-match'` on a file or folder update or
+- **Writes** — pass the etag as `'if-match'` on a file, folder, or web link update or
   delete, or a new file version upload. Box answers `412 Precondition
   Failed` (code `precondition_failed`) when the item changed since you read
-  it: read it again, reapply your change, retry. `If-Match` can't block a move.
+  it, and `runtime.isPreconditionFailed(err)` reports it: read it again,
+  reapply your change, retry. `If-Match` can't block a move.
 
 ```ts
 const file = await client.files.getIfModified(fileId, etag);
 if (file === undefined) {
   // unchanged since etag
 }
-try {
-  await client.files.update(fileId, body, { 'if-match': etag });
-} catch (err) {
-  if (err instanceof runtime.BoxApiError && err.status === 412) {
-    // changed since etag: re-read and retry
+
+// Re-read and retry: the update lands only on the version it was made from.
+for (let attempt = 1; ; attempt++) {
+  try {
+    await client.files.update(fileId, body, { 'if-match': etag });
+    break;
+  } catch (err) {
+    if (!runtime.isPreconditionFailed(err) || attempt === 3) throw err;
+    const current = await client.files.get(fileId);
+    etag = current.etag ?? undefined; // reapply your change to current here
   }
 }
 ```