frameio 3.2.3 → 4.1.1

package/dist/esm/oauth/http.mjs

@@ -0,0 +1,274 @@
+/**
+ * Internal HTTP helper for Adobe IMS token endpoint calls.
+ *
+ * Supports configurable timeouts, retries with exponential backoff,
+ * rate-limit handling (429), and response validation.
+ *
+ * Allows configurable IMS base URL for staging/alternative environments,
+ * and optional fetch injection for proxy, TLS, and custom HTTP handling.
+ */
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+import { AuthenticationError, ConfigurationError, NetworkError, RateLimitError, TokenExpiredError } from "./errors";
+import { noopLogger } from "./logger";
+// Default Adobe IMS base URL (production). Override via imsBaseUrl for staging.
+export const DEFAULT_IMS_BASE_URL = "https://ims-na1.adobelogin.com";
+/**
+ * Build authorize, token, and revoke URLs from an IMS base URL.
+ *
+ * @throws {Error} if the base URL does not use HTTPS.
+ */
+export function buildImsUrls(imsBaseUrl) {
+    if (!imsBaseUrl.toLowerCase().startsWith("https://")) {
+        throw new ConfigurationError(`imsBaseUrl must use HTTPS, got: ${imsBaseUrl}`);
+    }
+    const base = imsBaseUrl.replace(/\/$/, "");
+    return {
+        authorizeUrl: `${base}/ims/authorize/v2`,
+        tokenUrl: `${base}/ims/token/v3`,
+        revokeUrl: `${base}/ims/revoke`,
+    };
+}
+const DEFAULT_URLS = buildImsUrls(DEFAULT_IMS_BASE_URL);
+export const AUTHORIZE_URL = DEFAULT_URLS.authorizeUrl;
+export const TOKEN_URL = DEFAULT_URLS.tokenUrl;
+export const REVOKE_URL = DEFAULT_URLS.revokeUrl;
+// OAuth 2.0 RFC 6749 specifies space-separated scopes
+export const DEFAULT_SCOPES = "openid email profile offline_access additional_info.roles";
+export const S2S_SCOPES = "openid AdobeID frame.s2s.all";
+// Defaults
+export const DEFAULT_TIMEOUT = 30000; // milliseconds
+export const DEFAULT_MAX_RETRIES = 2;
+const RETRY_BACKOFF_SCHEDULE = [1000, 2000, 5000, 10000]; // ms
+const MAX_RETRY_AFTER_MS = 60000; // cap Retry-After to 60 s, matching Python
+const RETRYABLE_STATUS_CODES = new Set([500, 502, 503, 504]);
+/**
+ * Parse a Retry-After header value (seconds or HTTP-date).
+ * Returns milliseconds to wait, or undefined.
+ */
+function parseRetryAfter(header) {
+    if (!header)
+        return undefined;
+    const seconds = Number(header);
+    if (!isNaN(seconds))
+        return seconds * 1000;
+    const date = new Date(header);
+    if (isNaN(date.getTime()))
+        return undefined;
+    return Math.max(date.getTime() - Date.now(), 0);
+}
+/**
+ * Validate that a token response has the required fields.
+ */
+function validateTokenResponse(data, log) {
+    if (typeof data !== "object" || data === null) {
+        throw new AuthenticationError("invalid_response", "Token endpoint returned non-object response.");
+    }
+    const obj = data;
+    if (!("access_token" in obj) || typeof obj.access_token !== "string" || !obj.access_token) {
+        throw new AuthenticationError("invalid_response", "Token response missing or empty 'access_token'.");
+    }
+    const tokenType = obj.token_type;
+    if (tokenType == null) {
+        log.debug("Token response missing 'token_type' field.");
+    }
+    else if (typeof tokenType === "string" && tokenType.toLowerCase() !== "bearer") {
+        log.warn(`Unexpected token_type: ${tokenType} (expected 'bearer').`);
+    }
+    if (obj.expires_in !== undefined && obj.expires_in !== null) {
+        if (typeof obj.expires_in !== "number" || obj.expires_in <= 0) {
+            log.warn(`Invalid expires_in value (${obj.expires_in}), using default.`);
+            delete obj.expires_in;
+        }
+    }
+    return obj;
+}
+/** Sleep for a given number of milliseconds. */
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/**
+ * Send a POST to the Adobe IMS token endpoint.
+ *
+ * Rate-limit retries (429) are tracked separately from error retries
+ * (5xx / network failures), so a 429 does not consume the error retry
+ * budget and vice versa.
+ *
+ * @param data - Form-encoded body parameters.
+ * @param options - Timeout, retry, and logger options.
+ * @returns Parsed token response.
+ */
+export function tokenRequest(data_1) {
+    return __awaiter(this, arguments, void 0, function* (data, options = {}) {
+        var _a, _b, _c, _d, _e, _f;
+        const timeout = (_a = options.timeout) !== null && _a !== void 0 ? _a : DEFAULT_TIMEOUT;
+        const maxRetries = (_b = options.maxRetries) !== null && _b !== void 0 ? _b : DEFAULT_MAX_RETRIES;
+        const log = (_c = options.logger) !== null && _c !== void 0 ? _c : noopLogger;
+        const tokenUrl = (_d = options.tokenUrl) !== null && _d !== void 0 ? _d : TOKEN_URL;
+        const fetchFn = (_e = options.fetch) !== null && _e !== void 0 ? _e : (typeof globalThis.fetch !== "undefined" ? globalThis.fetch.bind(globalThis) : undefined);
+        if (fetchFn === undefined) {
+            throw new NetworkError("no fetch implementation available; please provide options.fetch or polyfill global fetch");
+        }
+        const body = new URLSearchParams(data).toString();
+        const maxErrorAttempts = maxRetries + 1;
+        const maxRateLimitAttempts = maxRetries + 1;
+        const maxTotal = maxErrorAttempts + maxRateLimitAttempts;
+        let errorAttempts = 0;
+        let rateLimitAttempts = 0;
+        for (let i = 0; i < maxTotal; i++) {
+            let response;
+            try {
+                log.debug(`Token request (errors=${errorAttempts}/${maxErrorAttempts}, rate_limits=${rateLimitAttempts}/${maxRateLimitAttempts})`);
+                const controller = new AbortController();
+                const timer = setTimeout(() => controller.abort(), timeout);
+                try {
+                    response = yield fetchFn(tokenUrl, {
+                        method: "POST",
+                        headers: { "Content-Type": "application/x-www-form-urlencoded" },
+                        body,
+                        signal: controller.signal,
+                    });
+                }
+                finally {
+                    clearTimeout(timer);
+                }
+            }
+            catch (err) {
+                errorAttempts++;
+                log.warn(`Network error on attempt ${errorAttempts}: ${err}`);
+                if (errorAttempts < maxErrorAttempts) {
+                    const backoff = RETRY_BACKOFF_SCHEDULE[Math.min(errorAttempts - 1, RETRY_BACKOFF_SCHEDULE.length - 1)];
+                    log.debug(`Retrying in ${backoff}ms...`);
+                    yield sleep(backoff);
+                    continue;
+                }
+                if (err instanceof Error && (err.name === "AbortError" || err.name === "TimeoutError")) {
+                    throw new NetworkError(`Token request timed out after ${timeout}ms (${maxErrorAttempts} attempts).`);
+                }
+                throw new NetworkError(`Token request failed after ${maxErrorAttempts} attempts: ${err instanceof Error ? err.message : String(err)}`);
+            }
+            // Rate limit handling — separate budget from error retries
+            if (response.status === 429) {
+                rateLimitAttempts++;
+                const retryAfterMs = parseRetryAfter(response.headers.get("retry-after"));
+                const retryAfterSec = retryAfterMs !== undefined ? retryAfterMs / 1000 : undefined;
+                log.warn(`Rate limited (429), attempt ${rateLimitAttempts}/${maxRateLimitAttempts}. Retry-After: ${retryAfterSec}s`);
+                if (rateLimitAttempts < maxRateLimitAttempts) {
+                    const waitMs = Math.min(retryAfterMs !== null && retryAfterMs !== void 0 ? retryAfterMs : RETRY_BACKOFF_SCHEDULE[Math.min(rateLimitAttempts - 1, RETRY_BACKOFF_SCHEDULE.length - 1)], MAX_RETRY_AFTER_MS);
+                    yield sleep(waitMs);
+                    continue;
+                }
+                throw new RateLimitError(retryAfterSec);
+            }
+            // Retryable server errors
+            if (RETRYABLE_STATUS_CODES.has(response.status)) {
+                errorAttempts++;
+                log.warn(`Server error ${response.status}, attempt ${errorAttempts}/${maxErrorAttempts}`);
+                if (errorAttempts < maxErrorAttempts) {
+                    const backoff = RETRY_BACKOFF_SCHEDULE[Math.min(errorAttempts - 1, RETRY_BACKOFF_SCHEDULE.length - 1)];
+                    yield sleep(backoff);
+                    continue;
+                }
+                // Fall through to error handling below
+            }
+            if (!response.ok) {
+                let errorCode = `http_${response.status}`;
+                let errorDesc;
+                try {
+                    const errBody = (yield response.json());
+                    errorCode = (_f = errBody.error) !== null && _f !== void 0 ? _f : errorCode;
+                    errorDesc = errBody.error_description;
+                }
+                catch (_g) {
+                    // ignore parse errors
+                }
+                // Detect expired refresh token
+                if ((errorCode === "invalid_grant" || errorCode === "invalid_token") &&
+                    errorDesc &&
+                    errorDesc.toLowerCase().includes("expired")) {
+                    log.error(`Token expired: ${errorCode}`);
+                    throw new TokenExpiredError(`${errorCode} — ${errorDesc}`);
+                }
+                log.error(`Authentication error: ${errorCode}`);
+                throw new AuthenticationError(errorCode, errorDesc);
+            }
+            // Success
+            let responseBody;
+            try {
+                responseBody = yield response.json();
+            }
+            catch (_h) {
+                throw new AuthenticationError("invalid_response", "Token endpoint returned non-JSON body");
+            }
+            const result = validateTokenResponse(responseBody, log);
+            log.info(`Token acquired (length=${result.access_token.length})`);
+            return result;
+        }
+        // Should not reach here, but just in case
+        throw new NetworkError("Token request failed after all retries.");
+    });
+}
+/**
+ * Revoke an access or refresh token.
+ *
+ * For confidential clients (with client_secret), credentials are sent via
+ * HTTP Basic Auth per RFC 7009. For public clients, the client_id is sent
+ * as a query parameter.
+ *
+ * This is best-effort — errors are logged but not thrown.
+ */
+export function revokeRequest(token_1, clientId_1, clientSecret_1) {
+    return __awaiter(this, arguments, void 0, function* (token, clientId, clientSecret, options = {}) {
+        var _a, _b, _c, _d;
+        const timeout = (_a = options.timeout) !== null && _a !== void 0 ? _a : DEFAULT_TIMEOUT;
+        const log = (_b = options.logger) !== null && _b !== void 0 ? _b : noopLogger;
+        const revokeUrl = (_c = options.revokeUrl) !== null && _c !== void 0 ? _c : REVOKE_URL;
+        const fetchFn = (_d = options.fetch) !== null && _d !== void 0 ? _d : (typeof globalThis.fetch !== "undefined" ? globalThis.fetch.bind(globalThis) : undefined);
+        if (fetchFn === undefined) {
+            log.warn("Token revocation skipped: no fetch implementation available");
+            return;
+        }
+        const headers = {
+            "Content-Type": "application/x-www-form-urlencoded",
+        };
+        const data = { token };
+        let url = revokeUrl;
+        if (clientSecret) {
+            // Confidential client: use HTTP Basic Auth (RFC 7009 §2.1)
+            const credentials = btoa(`${clientId}:${clientSecret}`);
+            headers["Authorization"] = `Basic ${credentials}`;
+        }
+        else {
+            // Public client: send client_id as query parameter
+            url = `${revokeUrl}?${new URLSearchParams({ client_id: clientId }).toString()}`;
+        }
+        try {
+            const controller = new AbortController();
+            const timer = setTimeout(() => controller.abort(), timeout);
+            try {
+                const response = yield fetchFn(url, {
+                    method: "POST",
+                    headers,
+                    body: new URLSearchParams(data).toString(),
+                    signal: controller.signal,
+                });
+                if (!response.ok) {
+                    log.warn(`Token revocation returned status ${response.status}`);
+                }
+            }
+            finally {
+                clearTimeout(timer);
+            }
+        }
+        catch (err) {
+            log.warn(`Token revocation failed: ${err}`);
+        }
+    });
+}

package/dist/esm/oauth/index.d.mts

@@ -0,0 +1,34 @@
+/**
+ * frameio OAuth 2.0 authentication for the Frame.io V4 SDK.
+ *
+ * Provides four authentication flows:
+ *
+ * - {@link ServerToServerAuth} — client_credentials grant (backend services)
+ * - {@link WebAppAuth} — authorization_code grant (server-side apps)
+ * - {@link SPAAuth} — authorization_code + PKCE (browser apps)
+ * - {@link NativeAppAuth} — authorization_code + PKCE (desktop / mobile)
+ *
+ * @example
+ * ```ts
+ * import { FrameioClient, ServerToServerAuth } from 'frameio';
+ *
+ * const auth = new ServerToServerAuth({ clientId: '...', clientSecret: '...' });
+ * const client = new FrameioClient({ token: () => auth.getToken() });
+ * ```
+ *
+ * @packageDocumentation
+ */
+export type { BaseAuthOptions } from "./BaseAuth";
+export { ServerToServerAuth } from "./ServerToServerAuth";
+export type { ServerToServerAuthOptions } from "./ServerToServerAuth";
+export { WebAppAuth } from "./WebAppAuth";
+export type { WebAppAuthOptions } from "./WebAppAuth";
+export { SPAAuth } from "./SPAAuth";
+export type { SPAAuthOptions, AuthorizationUrlResult } from "./SPAAuth";
+export { NativeAppAuth } from "./NativeAppAuth";
+export type { NativeAppAuthOptions } from "./NativeAppAuth";
+export { FrameioAuthError, AuthenticationError, TokenExpiredError, NetworkError, RateLimitError, PKCEError, ConfigurationError, } from "./errors";
+export type { Logger } from "./logger";
+export { noopLogger } from "./logger";
+export { DEFAULT_IMS_BASE_URL, buildImsUrls } from "./http";
+export type { TokenResponse, ExportedTokens, OnTokenRefreshed } from "./TokenManager";

package/dist/esm/oauth/index.mjs

@@ -0,0 +1,30 @@
+/**
+ * frameio OAuth 2.0 authentication for the Frame.io V4 SDK.
+ *
+ * Provides four authentication flows:
+ *
+ * - {@link ServerToServerAuth} — client_credentials grant (backend services)
+ * - {@link WebAppAuth} — authorization_code grant (server-side apps)
+ * - {@link SPAAuth} — authorization_code + PKCE (browser apps)
+ * - {@link NativeAppAuth} — authorization_code + PKCE (desktop / mobile)
+ *
+ * @example
+ * ```ts
+ * import { FrameioClient, ServerToServerAuth } from 'frameio';
+ *
+ * const auth = new ServerToServerAuth({ clientId: '...', clientSecret: '...' });
+ * const client = new FrameioClient({ token: () => auth.getToken() });
+ * ```
+ *
+ * @packageDocumentation
+ */
+// Auth flows
+export { ServerToServerAuth } from "./ServerToServerAuth";
+export { WebAppAuth } from "./WebAppAuth";
+export { SPAAuth } from "./SPAAuth";
+export { NativeAppAuth } from "./NativeAppAuth";
+// Errors
+export { FrameioAuthError, AuthenticationError, TokenExpiredError, NetworkError, RateLimitError, PKCEError, ConfigurationError, } from "./errors";
+export { noopLogger } from "./logger";
+// Config
+export { DEFAULT_IMS_BASE_URL, buildImsUrls } from "./http";

package/dist/esm/oauth/logger.d.mts

@@ -0,0 +1,17 @@
+/**
+ * Pluggable logger interface for frameio-auth-sdk.
+ *
+ * Consumers can supply any object matching this interface (e.g. `console`,
+ * `winston`, `pino`) via the `logger` option on auth class constructors.
+ *
+ * The default is a no-op logger (silent).
+ */
+/** Logger interface accepted by all frameio-auth-sdk classes. */
+export interface Logger {
+    debug(msg: string): void;
+    info(msg: string): void;
+    warn(msg: string): void;
+    error(msg: string): void;
+}
+/** Silent no-op logger — the default when no logger is provided. */
+export declare const noopLogger: Logger;

package/dist/esm/oauth/logger.mjs

@@ -0,0 +1,15 @@
+/**
+ * Pluggable logger interface for frameio-auth-sdk.
+ *
+ * Consumers can supply any object matching this interface (e.g. `console`,
+ * `winston`, `pino`) via the `logger` option on auth class constructors.
+ *
+ * The default is a no-op logger (silent).
+ */
+/** Silent no-op logger — the default when no logger is provided. */
+export const noopLogger = {
+    debug() { },
+    info() { },
+    warn() { },
+    error() { },
+};

package/dist/esm/oauth/pkce.d.mts

@@ -0,0 +1,30 @@
+/**
+ * PKCE (Proof Key for Code Exchange) utilities.
+ *
+ * Implements code_verifier generation and S256 code_challenge derivation
+ * per RFC 7636.
+ *
+ * Uses the Web Crypto API (`globalThis.crypto`) so it works in both
+ * Node.js (>=18) and browsers.
+ */
+/**
+ * Generate a cryptographically random code verifier.
+ *
+ * Uses `globalThis.crypto.getRandomValues` which is available in
+ * browsers and Node.js >= 18.
+ *
+ * @param length - Length of the verifier (43–128 inclusive). Defaults to 128.
+ * @returns A random string of unreserved URI characters.
+ */
+export declare function generateCodeVerifier(length?: number): string;
+/**
+ * Derive the S256 code challenge from a code verifier.
+ *
+ * `code_challenge = BASE64URL(SHA256(code_verifier))`
+ *
+ * Uses `crypto.subtle.digest` which is available in browsers and Node.js >= 18.
+ *
+ * @param verifier - The code verifier string.
+ * @returns Base64url-encoded (no padding) SHA-256 hash.
+ */
+export declare function generateCodeChallenge(verifier: string): Promise<string>;

package/dist/esm/oauth/pkce.mjs

@@ -0,0 +1,98 @@
+/**
+ * PKCE (Proof Key for Code Exchange) utilities.
+ *
+ * Implements code_verifier generation and S256 code_challenge derivation
+ * per RFC 7636.
+ *
+ * Uses the Web Crypto API (`globalThis.crypto`) so it works in both
+ * Node.js (>=18) and browsers.
+ */
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+/** Unreserved URI characters allowed in a code verifier (RFC 7636 §4.1). */
+const VERIFIER_CHARS = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-._~";
+const MIN_VERIFIER_LENGTH = 43;
+const MAX_VERIFIER_LENGTH = 128;
+const DEFAULT_VERIFIER_LENGTH = 128;
+/**
+ * Generate a cryptographically random code verifier.
+ *
+ * Uses `globalThis.crypto.getRandomValues` which is available in
+ * browsers and Node.js >= 18.
+ *
+ * @param length - Length of the verifier (43–128 inclusive). Defaults to 128.
+ * @returns A random string of unreserved URI characters.
+ */
+export function generateCodeVerifier(length = DEFAULT_VERIFIER_LENGTH) {
+    if (length < MIN_VERIFIER_LENGTH || length > MAX_VERIFIER_LENGTH) {
+        throw new RangeError(`code_verifier length must be between ${MIN_VERIFIER_LENGTH} and ${MAX_VERIFIER_LENGTH}, got ${length}`);
+    }
+    // Rejection sampling: discard random bytes that would introduce modulo bias.
+    // Only accept values below the largest multiple of the charset length that
+    // fits in a byte (256), so every character has equal probability.
+    const charsetLen = VERIFIER_CHARS.length; // 66
+    const limit = 256 - (256 % charsetLen); // 252
+    const chars = new Array(length);
+    // Batch random bytes; refill when exhausted. Oversize slightly to absorb the
+    // ~1.6% rejection rate without a second refill in the common case.
+    let buf = new Uint8Array(Math.ceil(length * 1.1));
+    globalThis.crypto.getRandomValues(buf);
+    let bufPos = 0;
+    for (let i = 0; i < length;) {
+        if (bufPos >= buf.length) {
+            buf = new Uint8Array(length);
+            globalThis.crypto.getRandomValues(buf);
+            bufPos = 0;
+        }
+        const b = buf[bufPos++];
+        if (b < limit) {
+            chars[i] = VERIFIER_CHARS[b % charsetLen];
+            i++;
+        }
+        // else: discard and advance to next byte
+    }
+    return chars.join("");
+}
+/**
+ * Derive the S256 code challenge from a code verifier.
+ *
+ * `code_challenge = BASE64URL(SHA256(code_verifier))`
+ *
+ * Uses `crypto.subtle.digest` which is available in browsers and Node.js >= 18.
+ *
+ * @param verifier - The code verifier string.
+ * @returns Base64url-encoded (no padding) SHA-256 hash.
+ */
+export function generateCodeChallenge(verifier) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const data = new TextEncoder().encode(verifier);
+        const hashBuffer = yield globalThis.crypto.subtle.digest("SHA-256", data);
+        const hashArray = new Uint8Array(hashBuffer);
+        // Base64url encode (no padding)
+        let base64 = "";
+        const len = hashArray.length;
+        for (let i = 0; i < len; i += 3) {
+            const a = hashArray[i];
+            const b = i + 1 < len ? hashArray[i + 1] : 0;
+            const c = i + 2 < len ? hashArray[i + 2] : 0;
+            base64 += toBase64Url((a >> 2) & 0x3f);
+            base64 += toBase64Url(((a & 0x03) << 4) | ((b >> 4) & 0x0f));
+            if (i + 1 < len)
+                base64 += toBase64Url(((b & 0x0f) << 2) | ((c >> 6) & 0x03));
+            if (i + 2 < len)
+                base64 += toBase64Url(c & 0x3f);
+        }
+        return base64;
+    });
+}
+const BASE64URL_CHARS = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_";
+function toBase64Url(index) {
+    return BASE64URL_CHARS[index];
+}

package/dist/esm/oauth/validation.d.mts

@@ -0,0 +1,17 @@
+/**
+ * Input validation helpers for frameio-auth-sdk.
+ */
+import type { ExportedTokens } from "./TokenManager";
+/**
+ * Validate that a redirect URI uses HTTPS, except for loopback addresses
+ * where HTTP is allowed for local development.
+ *
+ * @throws {ConfigurationError} if the URI uses http:// with a non-loopback host.
+ */
+export declare function validateRedirectUriScheme(uri: string): void;
+/**
+ * Validate the structure of an exported token object before importing.
+ *
+ * @throws {ConfigurationError} if any field has an unexpected type.
+ */
+export declare function validateTokenImport(data: unknown): asserts data is ExportedTokens;

package/dist/esm/oauth/validation.mjs

@@ -0,0 +1,51 @@
+/**
+ * Input validation helpers for frameio-auth-sdk.
+ */
+import { ConfigurationError } from "./errors";
+/** Hosts that are allowed to use http:// redirect URIs. */
+const LOOPBACK_HOSTS = new Set(["localhost", "127.0.0.1", "[::1]"]);
+/**
+ * Validate that a redirect URI uses HTTPS, except for loopback addresses
+ * where HTTP is allowed for local development.
+ *
+ * @throws {ConfigurationError} if the URI uses http:// with a non-loopback host.
+ */
+export function validateRedirectUriScheme(uri) {
+    const lower = uri.toLowerCase();
+    if (!lower.startsWith("http://")) {
+        return; // https:// and custom schemes are always allowed
+    }
+    const hostPart = lower.slice("http://".length);
+    // Extract host, handling IPv6 brackets (e.g. [::1])
+    let host;
+    if (hostPart.startsWith("[")) {
+        const bracketEnd = hostPart.indexOf("]");
+        host = bracketEnd !== -1 ? hostPart.slice(0, bracketEnd + 1) : hostPart.split("/")[0];
+    }
+    else {
+        host = hostPart.split("/")[0].split(":")[0];
+    }
+    if (!LOOPBACK_HOSTS.has(host)) {
+        throw new ConfigurationError(`Redirect URI must use HTTPS for non-loopback hosts, got: ${uri}`);
+    }
+}
+/**
+ * Validate the structure of an exported token object before importing.
+ *
+ * @throws {ConfigurationError} if any field has an unexpected type.
+ */
+export function validateTokenImport(data) {
+    if (typeof data !== "object" || data === null) {
+        throw new ConfigurationError("Token import data must be a non-null object.");
+    }
+    const obj = data;
+    if ("access_token" in obj && obj.access_token !== null && typeof obj.access_token !== "string") {
+        throw new ConfigurationError(`access_token must be a string or null, got ${typeof obj.access_token}`);
+    }
+    if ("refresh_token" in obj && obj.refresh_token !== null && typeof obj.refresh_token !== "string") {
+        throw new ConfigurationError(`refresh_token must be a string or null, got ${typeof obj.refresh_token}`);
+    }
+    if ("expires_at" in obj && typeof obj.expires_at !== "number") {
+        throw new ConfigurationError(`expires_at must be a number, got ${typeof obj.expires_at}`);
+    }
+}

package/dist/esm/version.d.mts

@@ -1 +1 @@
-export declare const SDK_VERSION = "3.2.3";
+export declare const SDK_VERSION = "4.1.0";

package/dist/esm/version.mjs

@@ -1 +1 @@
-export const SDK_VERSION = "3.2.3";
+export const SDK_VERSION = "4.1.0";

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "frameio",
-    "version": "3.2.3",
+    "version": "4.1.1",
     "private": false,
     "repository": {
         "type": "git",

package/reference.md

@@ -1642,7 +1642,7 @@ Create a new Version Stack under the parent folder. <br/>Rate Limits: 10 calls p
 ```typescript
 await client.versionStacks.create("b2702c44-c6da-4bb6-8bbd-be6e547ccf1b", "b2702c44-c6da-4bb6-8bbd-be6e547ccf1b", {
     data: {
-        file_ids: ["caeb2589-1ce1-45f4-ab94-3f5f87527cfa", "e768892b-dafe-4634-abf6-6e0e63624100"]
+        file_ids: ["bf6a7751-b5e4-4f2e-b7e4-67ee53d740e8", "0604f9c0-36a4-4b59-ab89-f48e3b172dc0"]
     }
 });
 
@@ -3548,7 +3548,7 @@ await client.shares.update("b2702c44-c6da-4bb6-8bbd-be6e547ccf1b", "b2702c44-c6d
         access: "public",
         description: "A descriptive summary of the share",
         downloading_enabled: true,
-        expiration: "2026-04-01T16:07:14Z",
+        expiration: "2026-04-15T00:53:07Z",
         name: "Share Name",
         passphrase: "as!dfj39sd(*"
     }
@@ -3990,7 +3990,7 @@ Add new asset share. <br/>Rate Limits: 10 calls per 1.00 minute(s) per account_u
 ```typescript
 await client.shares.addAsset("b2702c44-c6da-4bb6-8bbd-be6e547ccf1b", "b2702c44-c6da-4bb6-8bbd-be6e547ccf1b", {
     data: {
-        asset_id: "b3d93131-3b65-4a23-889b-0981fc8b8973"
+        asset_id: "f2631de7-7f1d-423e-825f-350106ad5332"
     }
 });
 
@@ -4174,9 +4174,9 @@ await client.shares.create("b2702c44-c6da-4bb6-8bbd-be6e547ccf1b", "b2702c44-c6d
     data: {
         type: "asset",
         access: "public",
-        asset_ids: ["2486de9e-ac4b-4490-9dfa-626f038144db", "9eddefaa-2e54-4134-8f1e-b9c8cf7e3541"],
+        asset_ids: ["ead05077-22fb-4f16-af36-44fdabb31c7f", "4cb5fe30-845a-4fc5-beb0-5f6e1e684a7c"],
         downloading_enabled: true,
-        expiration: "2026-04-01T16:07:14Z",
+        expiration: "2026-04-15T00:53:07Z",
         name: "Share Name",
         passphrase: "as!dfj39sd(*"
     }
@@ -4262,16 +4262,16 @@ Update metadata values across multiple files. <br/>Rate Limits: 10 calls per 1.0
 ```typescript
 await client.metadata.bulkUpdate("b2702c44-c6da-4bb6-8bbd-be6e547ccf1b", "b2702c44-c6da-4bb6-8bbd-be6e547ccf1b", {
     data: {
-        file_ids: ["6597eb4d-3137-4760-9c5e-6f59479908b8", "a4f42a72-f640-44fc-b9a9-2533d9d64df1"],
+        file_ids: ["055e9655-5445-425c-9158-4dcff313a8a1", "7e91a226-d1ac-4bea-afd1-9128c52ffc8d"],
         values: [{
-                field_definition_id: "2626b9ed-d32a-4eab-871e-038a956338c4",
+                field_definition_id: "174f1f07-3e07-4ad0-ac74-a27c0dc4a781",
                 value: [
                     {
-                        "id": "e0bfb74f-2139-4b25-81bd-18a8cc22cccc",
+                        "id": "f1ef4511-a8ff-4645-b406-47e3362ad15a",
                         "type": "user"
                     },
                     {
-                        "id": "edff6fbf-9b0c-44d8-81f9-f56a42a0263e",
+                        "id": "3a015842-e804-496a-abbe-577a332fb255",
                         "type": "account_user_group"
                     }
                 ]