Riferimento SDK TypeScript | Frame.io API Documentation

Installazione

npm i -s frameio

Utilizzo

Crea un’istanza e utilizza il client con quanto segue:

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

Tipi di richiesta e risposta

L’SDK esporta tutti i tipi di richiesta e risposta come interfacce TypeScript. È sufficiente importarli con il seguente spazio dei nomi:

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

Gestione delle eccezioni

Quando l’API restituisce un codice di stato diverso da quello di successo (risposta 4xx o 5xx), viene generata una sottoclasse del seguente errore.

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

Avanzate

Intestazioni aggiuntive

Per inviare intestazioni aggiuntive come parte della richiesta, utilizza l’opzione di richiesta headers.

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

Parametri aggiuntivi della stringa di richiesta

Per inviare parametri aggiuntivi della stringa come parte della richiesta, utilizza l’opzione di richiesta queryParams.

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

Nuovi tentativi

L’SDK può eseguire nuovi tentativi automatici con backoff esponenziale. Una richiesta viene ripetuta finché è considerata ripetibile e il numero di tentativi non supera il limite configurato (predefinito: 2).

Una richiesta è considerata ripetibile quando viene restituito uno dei seguenti codici di stato HTTP:

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

Utilizza l’opzione di richiesta maxRetries per configurare questo comportamento.

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

Timeout

L’SDK utilizza per impostazione predefinita un timeout di 60 secondi. Usa l’opzione timeoutInSeconds per configurare questo comportamento.

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

Annullamento delle richieste

L’SDK consente agli utenti di annullare le richieste in qualsiasi momento passando un segnale di annullamento (abort).

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

Accesso ai dati di risposta non elaborati

L’SDK consente di accedere ai dati di risposta non elaborati, comprese le intestazioni, tramite il metodo .withRawResponse(). Il metodo .withRawResponse() restituisce una promessa che genera un oggetto con un valore data e una proprietà rawResponse.

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

Compatibilità dei runtime

L’SDK funziona nei seguenti runtime:

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

Personalizzazione del client di recupero

L’SDK consente di personalizzare il client HTTP sottostante e la funzione di recupero (Fetch). Se stai lavorando in un ambiente non supportato, questo ti permette di intervenire e garantire il funzionamento dell’SDK.

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

Riferimento

Autorizzazioni account

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

Elenca i ruoli utente per un account specifico.

Limiti di frequenza: 100 chiamate ogni 1,00 minuto per 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();
}

Parametri

accountId: Frameio.Uuid —

request: Frameio.AccountPermissionsIndexRequest

requestOptions: AccountPermissions.RequestOptions

Account

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

Elenca gli account per l’utente corrente.

Limiti di frequenza: 100 chiamate ogni 1,00 minuto per 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();
}

Parametri

request: Frameio.AccountsIndexRequest

requestOptions: Accounts.RequestOptions

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

Elenca i registri di controllo con alcune funzionalità di filtro tramite parametri di query.

Limiti di frequenza: 100 chiamate ogni 1,00 minuto per account_user

usage

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

Parametri

accountId: Frameio.FrameOrAdobeId —

request: Frameio.AuditlogIndexRequest

requestOptions: Accounts.RequestOptions

Autenticazione

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

Autenticati utilizzando la concessione client_credentials OAuth 2.0. Questo flusso non coinvolge un utente e non restituisce un token di aggiornamento. Quando il token di accesso scade, l’SDK ne richiede automaticamente uno nuovo utilizzando le credenziali client.

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

Parametri

clientId: string — ID cliente OAuth di Adobe IMS.

clientSecret: string — Secret del client OAuth di Adobe IMS.

scopes: string — Ambiti separati da spazi (OAuth 2.0 RFC 6749). Per impostazione predefinita, vengono impostati gli ambiti da server a server.

imsBaseUrl: string — URL di base IMS per ambienti temporanei/alternativi. Il valore predefinito è production.

fetch: typeof fetch — Implementazione fetch personalizzata (per proxy, TLS, ecc.).

onTokenRefreshed: OnTokenRefreshed — Callback opzionale attivato dopo ogni recupero di token.

timeout: number — Timeout della richiesta HTTP in secondi. Il valore predefinito è 30000.

maxRetries: number — Numero massimo di nuovi tentativi per errori transitori. Il valore predefinito è 2.

refreshBuffer: number — Secondi prima della scadenza per attivare l’aggiornamento proattivo. Il valore predefinito è 60.

logger: Logger — Istanza logger per l’output diagnostico. Metodi getToken(): Promessa<string></string> — Restituisce un token di accesso valido, aggiornandolo se necessario.. Passalo al client: new FrameioClient({ token: () => auth.getToken() }). authenticate(): Promessa<tokenresponse></tokenresponse> — Recupera esplicitamente un nuovo token di accesso. revoke(): Promessa<void></void> — Revoca i token lato server e cancella lo stato locale. exportTokens(): ExportedTokens — Esporta lo stato del token corrente per la persistenza. importTokens(data: ExportedTokens): void — Ripristina lo stato del token da un oggetto esportato in precedenza.

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

Autenticati utilizzando la concessione authorization_code OAuth 2.0.Usa questo metodo per applicazioni sul lato server che possono archiviare in modo sicuro un secret del client.

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

Parametri

clientId: string — ID cliente OAuth di Adobe IMS.

clientSecret: string — Secret del client OAuth di Adobe IMS.

redirectUri: string — URI di reindirizzamento registrato.

scopes: string — Ambiti separati da spazi (OAuth 2.0 RFC 6749).

imsBaseUrl: string — URL di base IMS per ambienti temporanei/alternativi.Il valore predefinito è production.

fetch: typeof fetch — Implementazione fetch personalizzata (per proxy, TLS, ecc.).

onTokenRefreshed: OnTokenRefreshed — Callback opzionale attivato dopo ogni aggiornamento di token.

timeout: number — Timeout della richiesta HTTP in secondi.Il valore predefinito è 30000.

maxRetries: number — Numero massimo di nuovi tentativi per errori transitori.Il valore predefinito è 2.

refreshBuffer: number — Secondi prima della scadenza per attivare l’aggiornamento proattivo.Il valore predefinito è 60.

logger: Logger — Istanza logger per l’output diagnostico.Metodi getToken(): Promessa<string></string> — Restituisce un token di accesso valido, aggiornandolo se necessario..getAuthorizationUrl({ state }): string — Crea l’URL di autorizzazione di Adobe IMS. Passa un valore CSRF/state opaco che sarà restituito. exchangeCode(code: string): Promessa<tokenresponse></tokenresponse> - Scambia un codice di autorizzazione per accedere e aggiornare i token. refresh(): Promessa<tokenresponse></tokenresponse> — Attivare manualmente l’aggiornamento di un token. revoke(): Promessa<void></void> — Revoca i token lato server e cancella lo stato locale.exportTokens(): ExportedTokens — Esporta lo stato del token corrente per la persistenza.importTokens(data: ExportedTokens): void — Ripristina lo stato del token da un oggetto esportato in precedenza.

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

Autenticati utilizzando authorization_code + PKCE (senza secret del client).Utilizza questa opzione per app a singola pagina basate su browser che non possono archiviare in sicurezza un secret del client.

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