SDK de TypeScript

O SDK de TypeScript do Contismo é o cliente oficial de TypeScript para a API de conteúdo GraphQL do Contismo. Use-o para consultar conteúdo, executar mutações, introspectar o esquema e gerar tipos TypeScript para o seu projeto.

O pacote é publicado no npm como @contismo/sdk.

Instalação

Instale o SDK no seu aplicativo:

pnpm add @contismo/sdk

O SDK exige Node.js 20 ou mais recente.

Autenticação

O SDK se autentica com uma chave de API GraphQL do Contismo e envia Authorization e o cabeçalho X-Environment automaticamente.

As chaves de API são criadas no Studio, em Configurações → Chaves de API.

Prefixo da chave	Acesso
gql_	Consultas e introspecção
gqlw_	Consultas, mutações e introspecção

Use uma chave gql_ para clientes de entrega somente leitura. Use uma chave gqlw_ só onde o aplicativo precisar criar, atualizar ou excluir conteúdo.

Início rápido

1. Crie contismo.config.ts na raiz do seu projeto.
2. Execute pnpm contismo generate para obter o esquema e gerar os tipos TypeScript.
3. Crie um cliente e consulte o conteúdo com fetch ou fetchOne.

import { defineConfig } from "@contismo/sdk/config";

export default defineConfig({
  client: {
    apiKey: "gql_...",
    endpoint: "https://graphql.contismo.com",
    environment: "master",
  },
});

pnpm contismo generate

import { ContismoClient } from "@contismo/sdk";
import { BlogPost } from "./generated/contismo-models";

const client = new ContismoClient();

const { items: posts } = await client.fetch(BlogPost, {
  select: {
    _id: true,
    title: true,
  },
  limit: 10,
});

O primeiro argumento de fetch é o ID de API do modelo de conteúdo no Studio, ou uma referência de modelo gerada a partir de contismo-models.ts (consulte Consultar conteúdo).

Configuração

As opções obrigatórias do cliente em contismo.config.ts são:

Opção	Descrição
apiKey	Chave de API GraphQL do Studio
endpoint	Endpoint GraphQL, em geral https://graphql.contismo.com
environment	ID de API do ambiente, enviado como X-Environment

Descoberta do arquivo de configuração

new ContismoClient() procura contismo.config.ts, contismo.config.mts, contismo.config.js, contismo.config.mjs, contismo.config.cjs ou contismo.config.json a partir do diretório de trabalho atual.

Adicione a configuração opcional de codegen quando quiser mudar os caminhos de saída:

import { defineConfig } from "@contismo/sdk/config";

export default defineConfig({
  client: {
    apiKey: "gql_...",
    endpoint: "https://graphql.contismo.com",
    environment: "master",
  },
  codegen: {
    outputDir: "./src/generated",
    outputFile: "contismo.ts",
    schemaDir: "./contismo",
  },
});

Por padrão, pnpm contismo generate grava:

• contismo/schema.json
• src/generated/contismo.ts — tipos de entrada, como Entry_BlogPost
• contismo-models.ts — registro de modelos, ContismoEntryMap e referências de modelo tipadas, como BlogPost

Configuração explícita do cliente

Se o aplicativo não usa um arquivo de configuração, passe as credenciais diretamente:

import { ContismoClient } from "@contismo/sdk";

const client = new ContismoClient({
  apiKey: "gql_...",
  endpoint: "https://graphql.contismo.com",
  environment: "master",
});

Se o arquivo de configuração estiver em outro lugar, passe o caminho:

const client = new ContismoClient({
  config: "./config/contismo.config.ts",
});

Introspecção

Use introspect para ler o esquema GraphQL de forma programática. Ele usa as mesmas credenciais das consultas de conteúdo: uma chave de API GraphQL (gql_ ou gqlw_) e um ambiente. Se a chave ou o ambiente estiver errado, a API retorna um erro de autenticação em vez de uma falha genérica de introspecção.

const schema = await client.introspect();

O SDK também exporta writeIntrospectionResult se você quiser gravar o resultado em disco em um fluxo personalizado.

Consultar conteúdo

Use fetch para consultar uma lista de entradas com um objeto select no estilo do Prisma. fetchOne obtém uma única entrada pelo ID.

Referências de modelo

Depois de contismo generate, importe uma referência de modelo de contismo-models.ts. O tipo de retorno é inferido: não é preciso um genérico explícito.

import { ContismoClient } from "@contismo/sdk";
import { BlogPost } from "./generated/contismo-models";

const client = new ContismoClient();

const { items: posts } = await client.fetch(BlogPost, {
  select: {
    _id: true,
    title: true,
    author: {
      name: true,
    },
  },
  limit: 10,
});

const post = await client.fetchOne(BlogPost, {
  id: "entry-id-here",
  select: {
    _id: true,
    title: true,
  },
});

Campos de união

Em campos que retornam uma união GraphQL, agrupe cada seleção sob o nome do tipo membro gerado. O SDK transforma essas chaves em fragmentos inline:

import { ContismoClient } from "@contismo/sdk";
import { Guide } from "./generated/contismo-models";

const client = new ContismoClient();

const guide = await client.fetchOne(Guide, {
  id: "guide-id-here",
  select: {
    title: true,
    modularContent: {
      Component_Accordion: {
        type: true,
        items: {
          heading: true,
          content: { asHtml: true },
        },
      },
      Component_Content: {
        content: { asHtml: true },
      },
    },
  },
});

Use os nomes de membro dos tipos de esquema gerados, como Component_Accordion, Component_Content ou Entry_Guide. As seleções de união funcionam tanto com fetch quanto com fetchOne.

Recursos e CDN

Os campos de recurso das entradas retornam URLs da CDN. Selecione url e thumbnailUrl e, em seguida, use buildCdnUrl para acrescentar transformações de imagem:

import { ContismoClient, buildCdnUrl } from "@contismo/sdk";
import { BlogPost } from "./generated/contismo-models";

const client = new ContismoClient();

const { items: posts } = await client.fetch(BlogPost, {
  select: {
    _id: true,
    title: true,
    cover: {
      url: true,
      thumbnailUrl: true,
    },
  },
  limit: 10,
});

const cover = posts[0]?.cover;
const previewUrl = cover?.thumbnailUrl ?? cover?.url;
const heroUrl = cover?.url
  ? buildCdnUrl(cover.url, {
      w: 1200,
      fmt: "webp",
      q: 80,
    })
  : null;

A entrega pela CDN é pública: solicitações GET não precisam de uma chave de API. Prefira thumbnailUrl para prévias de listas e cartões quando ele estiver presente. Use a url completa com transformações para a imagem principal.

Para a referência completa dos parâmetros de transformação, consulte o guia de CDN de imagens.

GraphQL bruto

Use query quando quiser fornecer você mesmo o documento GraphQL:

const data = await client.query(
  `
  query BlogPost($id: ID!) {
    blogPost(id: $id) {
      _id
      title
    }
  }
`,
  { id: "entry-id-here" },
);

Isso é útil quando você quer controle total da operação ou quando copia uma consulta do Explorador GraphQL.

Mutações

As mutações exigem uma chave de API de leitura e gravação com o prefixo gqlw_. O SDK bloqueia chamadas a client.mutate() antes de fazer uma solicitação de rede quando o cliente está configurado com uma chave somente leitura gql_. As mutações de entradas de conteúdo usam {ModelApiId}Input (por exemplo, BlogPostInput) tanto para criar quanto para atualizar, e não {ModelApiId}CreateInput.

const client = new ContismoClient({
  apiKey: "gqlw_...",
  endpoint: "https://graphql.contismo.com",
  environment: "master",
});

await client.mutate(
  `
  mutation CreatePost($input: BlogPostInput!) {
    createBlogPost(input: $input) {
      _id
      _status
      title
    }
  }
`,
  {
    input: {
      title: "Hello world",
    },
  },
);

Para os formatos das mutações e os nomes de operação gerados, consulte a referência da API GraphQL.

Tratamento de erros

Entradas ausentes não lançam erro. Leituras singulares, como blogPost(id: …) e client.fetchOne(), retornam null quando nenhuma entrada corresponde (ID, localidade ou filtros de status incorretos). Confira o resultado em vez de usar try/catch:

const client = new ContismoClient();

const post = await client.fetchOne("BlogPost", {
  id: entryId,
  select: { _id: true, title: true },
});

if (post == null) {
  // Entry does not exist or does not match filters
}

Falhas de GraphQL, HTTP e do SDK lançam erro. Erros de configuração, de validação, de autenticação, limites de taxa e outros errors da API rejeitam a promessa como ContismoError (muitas vezes ContismoGraphQLError). Use isContismoError para tratá-los:

import {
  ContismoClient,
  ContismoGraphQLError,
  isContismoError,
} from "@contismo/sdk";

const client = new ContismoClient();

try {
  await client.query(`query { blogPostCollection { items { _id } } }`);
} catch (error) {
  if (isContismoError(error) && error instanceof ContismoGraphQLError) {
    console.error(error.code, error.message);
  }
}

Isso captura falhas de solicitação da API, e não um campo singular null quando um ID está ausente.

Documentação relacionada

• SDK
• CDN de imagens
• Gerenciar recursos
• API GraphQL
• Explorador GraphQL
• Chaves de API