Referência do SDK do TypeScript | Frame.io API Documentation

Instalação

npm i -s frameio

Uso

Instancie e use o cliente com o seguinte:

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",
    },
});

Tipos de solicitação e resposta

O SDK exporta todos os tipos de solicitação e resposta como interfaces TypeScript. Basta importá-los com o seguinte namespace:

import { Frameio } from "frameio";
const request: Frameio.UpdateFieldDefinitionParams = {
    ...
};

Tratamento de exceções

Quando a API retorna um código de status sem sucesso (resposta 4xx ou 5xx), uma subclasse do erro a seguir será gerada.

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);
    }
}

Avançado

Cabeçalhos adicionais

Se quiser enviar cabeçalhos adicionais como parte da solicitação, use a opção de solicitação headers.

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

Parâmetros adicionais da string de consulta

Se quiser enviar parâmetros adicionais da string de consulta como parte da solicitação, use a opção de solicitação queryParams.

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

Tentativas

O SDK é instrumentado com novas tentativas automáticas com backoff exponencial. Uma solicitação será repetida enquanto a solicitação for considerada repetível e o número de tentativas não tiver ultrapassado o limite configurado de novas tentativas (padrão: 2).

Uma solicitação é considerada repetível quando qualquer um dos seguintes códigos de status HTTP é retornado:

408 (Tempo-limite)
429 (Muitas solicitações)
5XX (Erros internos do servidor)

Use a opção de solicitação maxRetries para configurar esse comportamento.

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

Tempos-limite

O SDK usa um tempo-limite padrão de 60 segundos. Use a opção timeoutInSeconds para configurar esse comportamento.

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

Cancelamento de solicitações

O SDK permite que os usuários cancelem solicitações a qualquer momento passando um sinal de cancelamento.

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

Acessar dados brutos da resposta

O SDK fornece acesso aos dados brutos da resposta, incluindo cabeçalhos, por meio do método .withRawResponse().O método .withRawResponse() retorna uma promise que resulta em um objeto com uma propriedade data e uma propriedade rawResponse.

const { data, rawResponse } = await client.metadataFields.metadataFieldDefinitionsCreate(...).withRawResponse();
console.log(data);
console.log(rawResponse.headers['X-My-Header']);

Compatibilidade de tempo de execução

O SDK funciona nos seguintes tempos de execução:

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

Personalização do cliente Fetch

O SDK fornece uma forma de personalizar o cliente HTTP / função Fetch subjacente. Se você estiver executando em um ambiente sem suporte, isso oferece uma forma de contornar a limitação e garantir que o SDK funcione.

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

Referência

Permissões da conta

client.accountPermissions.index(accountId, { ...params }) -> core.Page<Frameio.AccountUserRole>

Listar funções de usuário para uma determinada conta.

Limites de taxa: 100 chamadas por 1,00 minuto(s) por account_user

usage

const response = await client.accountPermissions.index("b2702c44-c6da-4bb6-8bbd-be6e547ccf1b", {
    include_deactivated: true,
    after: "<opaque_cursor>",
    page_size: 10,
    include_total_count: false,
});
for await (const item of response) {
    console.log(item);
}
// Or you can manually iterate page-by-page
let page = await client.accountPermissions.index("b2702c44-c6da-4bb6-8bbd-be6e547ccf1b", {
    include_deactivated: true,
    after: "<opaque_cursor>",
    page_size: 10,
    include_total_count: false,
});
while (page.hasNextPage()) {
    page = page.getNextPage();
}

Parâmetros

accountId: Frameio.Uuid —

request: Frameio.AccountPermissionsIndexRequest

requestOptions: AccountPermissions.RequestOptions

Contas

client.accounts.index({ ...params }) -> core.Page<Frameio.Account>

Listar contas do usuário atual.

Limites de taxa: 100 chamadas por 1,00 minuto(s) por account_user

usage

const response = await client.accounts.index({
    after: "<opaque_cursor>",
    page_size: 10,
    include_total_count: false,
});
for await (const item of response) {
    console.log(item);
}
// Or you can manually iterate page-by-page
let page = await client.accounts.index({
    after: "<opaque_cursor>",
    page_size: 10,
    include_total_count: false,
});
while (page.hasNextPage()) {
    page = page.getNextPage();
}

Parâmetros

request: Frameio.AccountsIndexRequest

requestOptions: Accounts.RequestOptions

client.accounts.auditlogIndex(accountId, { ...params }) -> Frameio.AuditLogsWithIncludesResponse

Listar logs de auditoria com recursos de filtragem por meio de parâmetros de consulta*

Limites de taxa: 100 chamadas por 1,00 minuto(s) por account_user

usage

await client.accounts.auditlogIndex("b2702c44-c6da-4bb6-8bbd-be6e547ccf1b", {
    include: "user",
    after: "<opaque_cursor>",
    page_size: 10,
    include_total_count: false,
});

Parâmetros

accountId: Frameio.FrameOrAdobeId —

request: Frameio.AuditlogIndexRequest

requestOptions: Accounts.RequestOptions

Autenticação

new ServerToServerAuth({ clientId, clientSecret, ... })

Autentica usando a concessão OAuth 2.0 client_credentials.Esse fluxo não envolve um usuário e não retorna um token de atualização. Quando o token de acesso expira, o SDK solicita automaticamente um novo usando as credenciais de cliente.

usage

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

Parâmetros

clientId: string — ID de cliente OAuth do Adobe IMS.

clientSecret: string — Client secret OAuth do Adobe IMS.

scopes: string — Escopos separados por espaços (OAuth 2.0 RFC 6749).O padrão são os escopos Server-to-Server.

imsBaseUrl: string — URL base do IMS para ambientes de staging/alternativos.O padrão é produção.

fetch: typeof fetch — Implementação de fetch personalizada (para proxy, TLS, etc.).

onTokenRefreshed: OnTokenRefreshed — Callback opcional disparado após cada busca de token.

timeout: number — Tempo-limite de solicitação HTTP em segundos.O padrão é 30000.

maxRetries: number — Máximo de repetições para falhas transitórias.O padrão é 2.

refreshBuffer: number — Segundos antes da expiração para acionar atualização proativa.O padrão é 60.

logger: Logger — Instância de logger para saída de diagnóstico.

Métodos

getToken(): Promise<string> — Retorna um token de acesso válido, atualizando-o se necessário. Passe-o ao cliente: new FrameioClient({ token: () => auth.getToken() }).

authenticate(): Promise<TokenResponse> — Busca explicitamente um novo token de acesso.

revoke(): Promise<void> — Revoga tokens no lado do servidor e limpa o estado local.

exportTokens(): ExportedTokens — Exporta o estado atual de tokens para persistência.

importTokens(data: ExportedTokens): void — Restaura o estado de tokens de um objeto exportado anteriormente.

new WebAppAuth({ clientId, clientSecret, redirectUri, ... })

Autentica usando a concessão OAuth 2.0 authorization_code.Use isso para aplicativos do lado do servidor que podem armazenar um client secret com segurança.

usage

import { randomBytes } from "crypto";
import { FrameioClient, WebAppAuth } from "frameio";
const auth = new WebAppAuth({
    clientId: "YOUR_CLIENT_ID",
    clientSecret: "YOUR_CLIENT_SECRET",
    redirectUri: "https://myapp.com/callback",
});
const url = auth.getAuthorizationUrl({ state: randomBytes(24).toString("hex") });
// redirect the user to url ...
await auth.exchangeCode("CODE_FROM_CALLBACK");
const client = new FrameioClient({ token: () => auth.getToken() });

Parâmetros

clientId: string — ID de cliente OAuth do Adobe IMS.

clientSecret: string — Client secret OAuth do Adobe IMS.

redirectUri: string — URI de redirecionamento registrado.

scopes: string — Escopos separados por espaços (OAuth 2.0 RFC 6749).

imsBaseUrl: string — URL base do IMS para ambientes de staging/alternativos.O padrão é produção.

fetch: typeof fetch — Implementação de fetch personalizada (para proxy, TLS, etc.).

onTokenRefreshed: OnTokenRefreshed — Callback opcional acionado após cada atualização de token

timeout: number — Tempo-limite de solicitação HTTP em segundos.O padrão é 30000.

maxRetries: number — Máximo de repetições para falhas transitórias.O padrão é 2.

refreshBuffer: number — Segundos antes da expiração para acionar atualização proativa.O padrão é 60.

logger: Logger — Instância de logger para saída de diagnóstico.

Métodos

getToken(): Promise<string> — Retorna um token de acesso válido, atualizando-o se necessário.

getAuthorizationUrl({ state }): string — Cria o URL de autorização do Adobe IMS. Passe um valor CSRF/state opaco que será ecoado de volta.

exchangeCode(code: string): Promise<TokenResponse> — Troca um código de autorização + verificador PKCE por tokens.

refresh(): Promise<TokenResponse> — Aciona manualmente uma atualização de token.

revoke(): Promise<void> — Revoga tokens no lado do servidor e limpa o estado local.

exportTokens(): ExportedTokens — Exporta o estado atual de tokens para persistência.

importTokens(data: ExportedTokens): void — Restaura o estado de tokens de um objeto exportado anteriormente.

new SPAAuth({ clientId, redirectUri, ... })

Autentica usando authorization_code + PKCE para aplicativos desktop e móveis.Use isto para aplicativos de página única baseados em navegador que não podem armazenar um Client Secret com segurança.

usage

import { randomBytes } from "crypto";
import { FrameioClient, SPAAuth } from "frameio";
const auth = new SPAAuth({
    clientId: "YOUR_CLIENT_ID",
    redirectUri: "https://myapp.com/cb",
});
const result = await auth.getAuthorizationUrl({ state: randomBytes(24).toString("hex") });
// redirect the user to result.url, store result.codeVerifier ...
await auth.exchangeCode({ code: "CODE_FROM_CALLBACK", codeVerifier: result.codeVerifier });
const client = new FrameioClient({ token: () => auth.getToken() });