@unofficialbox/box-open-sdk 0.7.1 → 0.9.0

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, 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 {
@@ -52,6 +53,12 @@ export declare class Client {
     private readonly fetchImpl;
     private readonly defaultHeaders;
     constructor(auth: Auth, options?: ClientOptions);
+    /** A new client that sends `As-User: userId` with every API request, so Box
+     * acts as that user (an admin, or a service account whose app may "make API
+     * calls using the as-user header"). It shares this client's auth flow and
+     * token cache, `fetch`, base URLs, and retry policy; this client is
+     * unchanged. Token requests never carry the header. */
+    withAsUserHeader(userId: string): Client;
     /** The configured base URL for a D-106 class, without a trailing slash. */
     baseUrl(name: string): string;
     /** A valid access token for the configured auth flow. The `signal` is
@@ -97,3 +104,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/auth.md

@@ -23,9 +23,9 @@ to act as a managed user:
 ```ts
 import { auth } from '@unofficialbox/box-open-sdk';
 const client = new Client(auth.clientCredentials({
-clientId: 'CLIENT_ID',
-clientSecret: 'CLIENT_SECRET',
-enterpriseId: 'ENTERPRISE_ID',
+  clientId: 'CLIENT_ID',
+  clientSecret: 'CLIENT_SECRET',
+  enterpriseId: 'ENTERPRISE_ID',
 }));
 ```
 
@@ -38,11 +38,11 @@ imported from the runtime's `./jwt` entry point and returns a promise:
 ```ts
 import { jwtAuth } from '@unofficialbox/box-open-sdk/jwt';
 const auth = await jwtAuth({
-clientId: 'CLIENT_ID',
-clientSecret: 'CLIENT_SECRET',
-publicKeyId: 'PUBLIC_KEY_ID',
-privateKeyPem: privateKeyPem, // optionally encrypted; set passphrase
-enterpriseId: 'ENTERPRISE_ID',
+  clientId: 'CLIENT_ID',
+  clientSecret: 'CLIENT_SECRET',
+  publicKeyId: 'PUBLIC_KEY_ID',
+  privateKeyPem: privateKeyPem, // optionally encrypted; set passphrase
+  enterpriseId: 'ENTERPRISE_ID',
 });
 const client = new Client(auth);
 ```
@@ -58,3 +58,30 @@ import { auth } from '@unofficialbox/box-open-sdk';
 const source = auth.oauth({ clientId: 'CLIENT_ID', clientSecret: 'CLIENT_SECRET' }, storedRefreshToken);
 const client = new Client(source);
 ```
+
+## Acting as another user
+
+An admin, or a service account whose app may *make API calls using the as-user
+header*, can act as another user. `withAsUserHeader` returns a new client whose
+every call sends Box's `As-User` header; it shares the original's auth (and
+token cache) and configuration, and the original is unchanged:
+
+```ts
+const userClient = client.withAsUserHeader('USER_ID');
+const me = await userClient.users.getMe(); // the user USER_ID
+```
+
+## Downscoping a token
+
+Exchange the session's access token for one limited to `scopes` and,
+optionally, to one item (its API URL) or shared link — e.g. to hand a
+browser-side preview a narrow token. The result has no refresh token; build
+a client from it as a developer token:
+
+```ts
+const down = await client.authorization.downscopeToken(
+  ['item_preview'],
+  'https://api.box.com/2.0/files/123',
+);
+const preview = new Client(auth.developerToken(down.access_token!));
+```

package/docs/errors.md

@@ -26,12 +26,12 @@ 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, and `runtime.isPreconditionFailed(err)` reports it: read it again,

package/docs/managers/web_links.md

@@ -25,6 +25,7 @@ const result = await client.webLinks.create({ /* … */ });
 |---|---|---|---|
 | `web_link_id` | path | `string` | yes |
 | `boxapi` | header | `string` | no |
+| `if-none-match` | header | `string` | no |
 
 **Returns:** `WebLink`
 
@@ -41,6 +42,7 @@ const result = await client.webLinks.get("WEB_LINK_ID");
 | Parameter | In | Type | Required |
 |---|---|---|---|
 | `web_link_id` | path | `string` | yes |
+| `if-match` | header | `string` | no |
 
 **Request body** (`application/json`): `UpdateWebLinkRequest`
 
@@ -59,6 +61,7 @@ const result = await client.webLinks.update("WEB_LINK_ID", { /* … */ });
 | Parameter | In | Type | Required |
 |---|---|---|---|
 | `web_link_id` | path | `string` | yes |
+| `if-match` | header | `string` | no |
 
 **Returns:** `void`
 

package/docs/pagination.md

@@ -7,7 +7,7 @@ that yields one entry at a time, threading the cursor for you — the list metho
 
 ```ts
 for await (const item of client.folders.listItems(folderId)) {
-// use item
+  // use item
 }
 ```
 
@@ -15,3 +15,19 @@ It walks every page until the response has no next cursor (or an empty page, for
 offset pagination), and owns a private copy of the options you pass, so your
 value is never mutated. The wire cursor (`next_marker` / `offset`, verbatim per
 TR-TS.2) is threaded through the options for you.
+
+## Events
+
+`client.events.stream` follows Box's long-poll event stream: it yields the events
+after `stream_position` (`'now'` when unset), each once — Box may deliver an
+event twice — then waits on a real-time server until Box reports a change. It
+lists a fresh server when Box asks it to reconnect, and retries a long poll that
+times out. It rejects when a call fails; `break` or an `AbortSignal` stops it.
+Stream positions keep every digit, even past `Number.MAX_SAFE_INTEGER`:
+
+```ts
+const controller = new AbortController();
+for await (const event of client.events.stream({}, controller.signal)) {
+  // use event
+}
+```

package/docs/webhooks.md

@@ -0,0 +1,34 @@
+<!-- Generated by box-gantry. DO NOT EDIT. -->
+# Webhooks
+
+Once you generate signature keys for your app (Developer Console → **Webhooks**
+→ **Manage signature keys**), Box signs every webhook delivery. Each
+`BOX-SIGNATURE-PRIMARY` / `BOX-SIGNATURE-SECONDARY` header is the base64
+HMAC-SHA256, under that key, of the request body followed by the
+`BOX-DELIVERY-TIMESTAMP` header (Box's
+[Verify webhook signatures](https://developer.box.com/guides/webhooks/v2/signatures-v2/)
+guide). `runtime.verifyWebhook` checks a delivery before you trust it:
+
+```ts
+import { runtime } from '@unofficialbox/box-open-sdk';
+
+// `body`: the raw request body (bytes or string); `headers`: a `Headers`
+// object or a plain record.
+const genuine = await runtime.verifyWebhook(body, headers, {
+  primaryKey,
+  secondaryKey,
+});
+if (!genuine) {
+  // reject: not from Box, altered, or stale
+}
+```
+
+- **Pass the body exactly as received.** Parsed and re-serialized JSON won't
+  verify.
+- **Either key may be missing.** A delivery is genuine when the signature of
+  any configured key matches, so you can rotate one key while the other keeps
+  verifying.
+- **Old or future deliveries are refused.** A delivery stamped more than ten
+  minutes ago (`maxAgeSeconds`) or in the future fails, which blocks replays.
+- **Header names match in any case**, and the comparison takes the same time
+  wherever a signature differs.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unofficialbox/box-open-sdk",
-  "version": "0.7.1",
+  "version": "0.9.0",
   "description": "Box API client for TypeScript (open source, community, punk rock) — typed models, async managers, and a fetch runtime with retry, backoff, and token refresh.",
   "keywords": ["box", "box-api", "sdk", "api-client", "typescript", "unofficial"],
   "license": "MIT",