Bibliotecas de cliente

A API REST é HTTP e JSON puros, e uma chamada de fetch já é uma forma perfeitamente boa de usá-la. As bibliotecas de cliente existem para as partes que ninguém gosta de escrever duas vezes: repetir corretamente uma requisição barrada pelo limite, tornar segura uma criação repetida e percorrer um cursor até o fim de uma lista.

Três bibliotecas, um contrato:

| Linguagem | Pacote | Código-fonte | | --- | --- | --- | | Node.js / TypeScript | @linkprofit/sdk | packages/sdk-node | | Python | linkprofit | sdk/python | | PHP | linkprofit/linkprofit-php | sdk/php |

Instalação

Os pacotes ainda não estão no npm, no PyPI nem no Packagist. A publicação depende das contas nesses registros; o código está completo e já pode ser instalado a partir de uma cópia local do repositório, e os comandos abaixo viram uma única linha npm install @linkprofit/sdk (e seus equivalentes) assim que as contas existirem.

Node, a partir de uma cópia local do repositório:

npm install /path/to/linkprofit/packages/sdk-node

Python, a partir de uma cópia local do repositório:

pip install /path/to/linkprofit/sdk/python

PHP, por um repositório do tipo path do Composer no seu composer.json:

{
  "repositories": [
    { "type": "path", "path": "/path/to/linkprofit/sdk/php" }
  ],
  "require": {
    "linkprofit/linkprofit-php": "*"
  }
}

O que as três fazem do mesmo jeito

As bibliotecas são propositalmente sem graça e propositalmente parecidas. Aprenda o comportamento uma vez e ele vale em todas as linguagens.

Autenticação. Você passa uma chave de espaço de trabalho (lp_live_…); o cliente define o cabeçalho Authorization em toda requisição. A URL base é uma opção, então o mesmo código pode rodar contra uma instância local nos testes. Veja Autenticação para escopos e rotação.

Novas tentativas que respeitam o servidor. Um 429 ou um 5xx transitório é repetido com backoff, e o Retry-After é respeitado em vez de adivinhado — o servidor já sabe quando a janela se libera. O número de tentativas tem teto, e uma requisição que falha por mérito próprio (validation_failed, conflict, not_found) nunca é repetida: repetir uma requisição errada só desperdiça o orçamento do limite de requisições.

Mutações idempotentes. Toda chamada que altera dados leva uma Idempotency-Key, então uma nova tentativa depois de um tempo limite de rede devolve a resposta armazenada em vez de criar um segundo link. Você pode fornecer a sua própria chave — o id de um pedido, o id de um job — quando a nova tentativa pode vir de outro processo ou de uma execução posterior. As chaves ficam armazenadas por 24 horas; a mesma chave com um corpo diferente responde 409.

Paginação por cursor como iterador. Os endpoints de listagem são paginados por cursor, e os clientes os expõem como iteradores: você percorre os links, o cliente busca a página seguinte quando a atual acaba e para quando o cursor é null. Sem aritmética de páginas, sem o risco do erro de um a mais que descarta uma linha em silêncio.

Erros como exceções. As falhas levantam o tipo de erro natural da linguagem, carregando o code da API, a mensagem legível e, nas falhas de validação, os details por campo. Ramifique conforme o código, e não conforme o texto da mensagem — os códigos são o contrato documentado.

Os tipos de requisição e de resposta do cliente Node são gerados a partir do mesmo documento OpenAPI que a referência renderiza — publicado em /openapi.json —, então os tipos não conseguem se afastar da API em execução. Os clientes Python e PHP seguem o mesmo documento à mão, no estilo idiomático de cada linguagem.

Início rápido

Cada pacote traz um README com a sua superfície completa; os trechos abaixo mostram o formato que as três compartilham — construa um cliente com uma chave, chame o grupo de recursos, receba de volta um objeto tipado.

Node

import { LinkProfit } from "@linkprofit/sdk";

const client = new LinkProfit({ apiKey: process.env.LINKPROFIT_API_KEY });

const created = await client.createLink({
  url: "https://example.com/summer-sale",
  title: "Summer sale",
});

console.log(created.data.short_url);

Python

import os

from linkprofit import LinkProfit

client = LinkProfit(os.environ["LINKPROFIT_API_KEY"])

created = client.create_link(
    {"url": "https://example.com/summer-sale", "title": "Summer sale"}
)

print(created["data"]["short_url"])

PHP

<?php

require __DIR__ . '/vendor/autoload.php';

use LinkProfit\LinkProfit;

$client = new LinkProfit(getenv('LINKPROFIT_API_KEY'));

$created = $client->createLink([
    'url' => 'https://example.com/summer-sale',
    'title' => 'Summer sale',
]);

echo $created['data']['short_url'];

Qual delas eu devo usar

• Node / TypeScript — a superfície mais completa, porque os seus tipos vêm direto do documento OpenAPI. A escolha natural para um backend JavaScript, uma função serverless ou um script de build.
• Python — para relatórios e trabalho com dados: puxe o analytics para um notebook, um job agendado ou o alimentador de um painel.
• PHP — para o mundo dos CMS. Um plugin do WordPress ou um serviço Laravel que encurta links conforme o conteúdo é publicado.
• Nenhuma delas — se a sua linguagem for outra, a API é HTTP comum. O início rápido começa pelo curl, e tudo o que os clientes fazem (novas tentativas, idempotência, cursores) é comportamento documentado que você implementa em cinquenta linhas.

Qualquer que seja a sua escolha, a referência da API é a lista completa de endpoints, campos e códigos de erro — as bibliotecas são uma conveniência em cima dela, nunca uma API diferente.

Também vale a leitura

• Limites de requisições — o orçamento dentro do qual a lógica de novas tentativas trabalha.
• Webhooks — receba os eventos empurrados até você em vez de ficar consultando.
• Servidor MCP — as mesmas operações a partir de um assistente de IA.