Frameio TypeScript Library

Frame.io is a cloud-based collaboration hub that allows video professionals to share files, comment on clips real-time, and compare different versions and edits of a clip.

Installation

npm i -s frameio

Reference

A full reference for this library is available here.

Usage

You can authenticate with a static token or OAuth 2.0 via frameio auth classes:

Static token (for legacy dev tokens or when you already have an access token):

const client = new FrameioClient({ token: "YOUR_TOKEN" });

OAuth 2.0 (for production with automatic token refresh):

import { FrameioClient, ServerToServerAuth } from "frameio";

const auth = new ServerToServerAuth({ clientId: "...", clientSecret: "..." });
const client = new FrameioClient({ token: () => auth.getToken() });

See the Authentication section below for all OAuth flows.

Example: creating a metadata field definition:

import { FrameioClient } from "frameio";

const client = new FrameioClient({ token: "YOUR_TOKEN" });
await client.metadataFields.metadataFieldDefinitionsCreate("b2702c44-c6da-4bb6-8bbd-be6e547ccf1b", {
    data: {
        field_type: "select",
        field_configuration: {
            enable_add_new: false,
            options: [
                {
                    display_name: "Option 1",
                },
                {
                    display_name: "Option 2",
                },
            ],
        },
        name: "Fields definition name",
    },
});

Authentication

The SDK supports two authentication options:

• Static token: Pass a string directly to token. Suitable for legacy dev tokens or when you already have an access token.
• OAuth 2.0: Use the built-in auth classes for automatic token management and refresh. Pass () => auth.getToken() to the client.

The SDK provides four OAuth 2.0 flows:

| Flow | Use Case | Classes | | ------------------------- | -------------------------------------------------- | -------------------- | | Server-to-Server | Backend services, scripts, no user interaction | ServerToServerAuth | | Web App | Server-side apps with client secret | WebAppAuth | | Single Page App (SPA) | Browser apps without a client secret (PKCE) | SPAAuth | | Native App | Desktop/mobile apps with custom URI schemes (PKCE) | NativeAppAuth |

Server-to-Server

For backend services and scripts that need Frame.io access without user interaction:

import { FrameioClient, ServerToServerAuth } from "frameio";

const auth = new ServerToServerAuth({ clientId: "...", clientSecret: "..." });
const client = new FrameioClient({ token: () => auth.getToken() });
// Tokens refresh automatically; no user interaction needed.

Web App

For server-side applications with a client secret:

import { FrameioClient, WebAppAuth } from "frameio";
import crypto from "crypto";

const auth = new WebAppAuth({
    clientId: "...",
    clientSecret: "...",
    redirectUri: "https://myapp.com/callback",
});

const url = auth.getAuthorizationUrl({ state: crypto.randomBytes(32).toString("hex") });
// Redirect user to url, then:
await auth.exchangeCode("CODE_FROM_CALLBACK");
const client = new FrameioClient({ token: () => auth.getToken() });

Single Page App (PKCE)

For browser-based apps that cannot store a client secret:

import { FrameioClient, SPAAuth } from "frameio";

const auth = new SPAAuth({ clientId: "...", redirectUri: "https://myapp.com/cb" });

const result = await auth.getAuthorizationUrl({ state: crypto.randomUUID() });
// Redirect user to result.url, store result.codeVerifier, then:
await auth.exchangeCode({ code: "CODE", codeVerifier: result.codeVerifier });
const client = new FrameioClient({ token: () => auth.getToken() });

Native App (PKCE with custom URI schemes)

For desktop and mobile applications:

import { NativeAppAuth } from "frameio";

const auth = new NativeAppAuth({
    clientId: "...",
    redirectUri: "myapp://callback",
});
// Same PKCE flow as SPAAuth

Token Persistence

For Web App, SPA, and Native App flows, you can persist tokens to avoid re-authenticating on each app restart:

// After exchangeCode() — save tokens for later
const data = auth.exportTokens();
// Store data to file or database ...

// On next app start — restore and use
auth.importTokens(data);
const client = new FrameioClient({ token: () => auth.getToken() });

Revoking Tokens

To sign out and revoke the current access and refresh tokens:

await auth.revoke();

Staging / Non-Production

Use imsBaseUrl to point at a staging or alternative Adobe IMS environment:

const auth = new ServerToServerAuth({
    clientId: "...",
    clientSecret: "...",
    imsBaseUrl: "https://ims-na1-stg1.adobelogin.com",
});

Async / Concurrency

All auth flows use async/await natively. The getToken() method handles automatic token refresh and is safe to call concurrently — only one refresh request fires at a time.

For the full authentication guide, see the TypeScript Authentication Guide.

Request And Response Types

The SDK exports all request and response types as TypeScript interfaces. Simply import them with the following namespace:

import { Frameio } from "frameio";

const request: Frameio.UpdateFieldDefinitionParams = {
    ...
};

Exception Handling

When the API returns a non-success status code (4xx or 5xx response), a subclass of the following error will be thrown.

import { FrameioError } from "frameio";

try {
    await client.metadataFields.metadataFieldDefinitionsCreate(...);
} catch (err) {
    if (err instanceof FrameioError) {
        console.log(err.statusCode);
        console.log(err.message);
        console.log(err.body);
        console.log(err.rawResponse);
    }
}

For OAuth flows, additional exceptions are available:

• AuthenticationError — token exchange or refresh failed
• TokenExpiredError — refresh token expired; user must re-authenticate
• ConfigurationError — invalid configuration (e.g. missing clientId)
• NetworkError, RateLimitError — network or rate limit issues

import { AuthenticationError, TokenExpiredError } from "frameio";

try {
    await auth.exchangeCode("...");
} catch (error) {
    if (error instanceof AuthenticationError) {
        console.error(error.errorCode, error.errorDescription);
    } else if (error instanceof TokenExpiredError) {
        // Redirect user to sign in again
    }
}

Advanced

Additional Headers

If you would like to send additional headers as part of the request, use the headers request option.

const response = await client.metadataFields.metadataFieldDefinitionsCreate(..., {
    headers: {
        'X-Custom-Header': 'custom value'
    }
});

Additional Query String Parameters

If you would like to send additional query string parameters as part of the request, use the queryParams request option.

const response = await client.metadataFields.metadataFieldDefinitionsCreate(..., {
    queryParams: {
        'customQueryParamKey': 'custom query param value'
    }
});

Retries

The SDK is instrumented with automatic retries with exponential backoff. A request will be retried as long as the request is deemed retryable and the number of retry attempts has not grown larger than the configured retry limit (default: 2).

A request is deemed retryable when any of the following HTTP status codes is returned:

• 408 (Timeout)
• 429 (Too Many Requests)
• 5XX (Internal Server Errors)

Use the maxRetries request option to configure this behavior.

const response = await client.metadataFields.metadataFieldDefinitionsCreate(..., {
    maxRetries: 0 // override maxRetries at the request level
});

Timeouts

The SDK defaults to a 60 second timeout. Use the timeoutInSeconds option to configure this behavior.

const response = await client.metadataFields.metadataFieldDefinitionsCreate(..., {
    timeoutInSeconds: 30 // override timeout to 30s
});

Aborting Requests

The SDK allows users to abort requests at any point by passing in an abort signal.

const controller = new AbortController();
const response = await client.metadataFields.metadataFieldDefinitionsCreate(..., {
    abortSignal: controller.signal
});
controller.abort(); // aborts the request

Access Raw Response Data

The SDK provides access to raw response data, including headers, through the .withRawResponse() method. The .withRawResponse() method returns a promise that results to an object with a data and a rawResponse property.

const { data, rawResponse } = await client.metadataFields.metadataFieldDefinitionsCreate(...).withRawResponse();

console.log(data);
console.log(rawResponse.headers['X-My-Header']);

Runtime Compatibility

The SDK works in the following runtimes:

• Node.js 18+
• Vercel
• Cloudflare Workers
• Deno v1.25+
• Bun 1.0+
• React Native

Customizing Fetch Client

The SDK provides a way for you to customize the underlying HTTP client / Fetch function. If you're running in an unsupported environment, this provides a way for you to break glass and ensure the SDK works.

import { FrameioClient } from "frameio";

const client = new FrameioClient({
    ...
    fetcher: // provide your implementation here
});

Contributing

While we value open-source contributions to this SDK, this library is generated programmatically. Additions made directly to this library would have to be moved over to our generation code, otherwise they would be overwritten upon the next generated release. Feel free to open a PR as a proof of concept, but know that we will not be able to merge it as-is. We suggest opening an issue first to discuss with us!

On the other hand, contributions to the README are always very welcome!