Referência da API

Esta página descreve a API pública do pacote @eyedux/sdk e o contrato HTTP usado pelo Eyedux.

Base URL e autenticação

O SDK usa a base fixa https://api.eyedux.com e injeta o header abaixo em toda requisição:

Authorization: Bearer <api_key>

O backend infere a organização pela API key. Não envie organization_id no payload. O cliente funciona em browsers, React e React Native, portanto o SDK não impede o uso direto da key nesses ambientes. Como ela pode ser extraída do bundle ou aplicativo, prefira um backend para chaves privilegiadas.

Construtores

`createEyeduxClient`

function createEyeduxClient(
  apiKey: string,
  options?: EyeduxClientOptions,
): EyeduxClient;

Cria um cliente. A API key é removida de espaços nas extremidades e uma key vazia lança EyeduxValidationError com código EMPTY_API_KEY.

Opção	Tipo	Padrão	Descrição
`projectId`	`string`	nenhum	Projeto padrão para novos eventos
`timeoutMs`	`number`	`30000`	Timeout por request, em milissegundos
`defaultMetadata`	`Record<string, unknown>`	nenhum	Metadata padrão, sobrescrita pelo evento
`fetch`	`typeof fetch`	`globalThis.fetch`	Implementação de transporte customizada

`createEyeduxClientWithConfig`

function createEyeduxClientWithConfig(
  config: EyeduxClientConfig,
): EyeduxClient;

Versão explícita que exige apiKey e projectId; ambos são validados antes da criação do cliente.

`createEyeduxClientFromEnv`

function createEyeduxClientFromEnv(
  options?: EyeduxClientOptions,
): EyeduxClient;

Lê somente EYEDUX_API_KEY em runtimes Node.js. Defina o projeto em options.projectId ou em cada chamada a createEvent.

Métodos do cliente

`createEvent`

client.createEvent(
  input: CreateEventInput,
  options?: RequestOptions,
): Promise<EyeduxEvent>;

Envia POST /public/logs. input.projectId tem precedência sobre o projeto padrão; se não houver um projeto, lança EyeduxValidationError com código EMPTY_PROJECT_ID.

Campo	Tipo	Obrigatório
`projectId`	`string`	Sim, no input ou na configuração
`type`	`string`	Sim
`properties`	`Record<string, unknown>`	Sim
`typeGroup`	`string`	Não
`message`	`string`	Não; máximo de 500 caracteres
`eyeduxType`	`EventEyeduxType`	Não
`externalObject`	`EventObject`	Não
`correlationObject`	`EventObject`	Não
`metadata`	`Record<string, unknown>`	Não

O SDK serializa os campos para snake_case na API: project_id, type_group, eyedux_type, external_object e correlation_object. message mantém o mesmo nome.

Para eventos audit, use AuditProperties em properties. actor e target são objetos obrigatórios. actor.type, actor.source, target.type, target.id e target.source devem ser strings não vazias; actor.id é obrigatório, exceto para actor.type = "anonymous". result aceita success, failure, in_review ou denied, e reason é obrigatório para failure e denied. changes é aceito para descrever alterações de estado.

`listEvents`

client.listEvents(
  input?: ListEventsInput,
  options?: RequestOptions,
): Promise<EyeduxEvent[]>;

Executa GET /public/logs. Os filtros opcionais e cumulativos são type e correlationId, serializado como correlation_id. Uma lista vazia, ou uma resposta com data: null, resulta em [].

`findEventByExternalId`

client.findEventByExternalId(
  externalId: string,
  options?: RequestOptions,
): Promise<EyeduxEvent>;

Executa GET /public/logs/external/:external_id, codificando o ID para uso no path. Uma string vazia lança EyeduxValidationError com código EMPTY_EXTERNAL_ID.

Métodos de emissão

client.emit(input, options);
client.emitError(input, options);
client.emitCritical(input, options);
client.emitWarning(input, options);
client.emitLog(input, options);
client.emitDebug(input, options);
client.emitInfo(input, options);
client.emitAudit(input, options);
client.emitMetric(input, options);

emit usa input.eyeduxType. Os atalhos aplicam suas categorias correspondentes. emitError adiciona contexto de diagnóstico às propriedades, copiando o objeto de entrada.

Tipos

`EventEyeduxType`

const EventEyeduxType = {
  SystemCritical: "system-critical",
  SystemError: "system-error",
  SystemWarning: "system-warning",
  SystemLog: "system-log",
  SystemDebug: "system-debug",
  SystemInfo: "system-info",
  Audit: "audit",
  Metric: "metric",
} as const;

`MetricUnit` e `MetricProperties`

const MetricUnit = {
  Count: "count",
  Bytes: "bytes",
  Milliseconds: "milliseconds",
  Seconds: "seconds",
  Percent: "percent",
  Ratio: "ratio",
} as const;

interface MetricProperties {
  value: number;
  unit: MetricUnit;
  dimensions?: Record<string, string>;
}

emitMetric envia eyedux_type: "metric" e valida as propriedades antes da requisição: o valor deve ser finito, percent fica entre 0 e 100, ratio entre 0 e 1, e dimensions aceita até 10 pares, com chaves e valores dentro dos limites da API. MetricProperties contém apenas value, unit e dimensions.

`EventObject`

interface EventObject {
  id: string;
  property: string;
  source?: string;
}

interface AuditActor {
  type: string;
  id?: string;
  source: string;
}

interface AuditTarget {
  type: string;
  id: string;
  source: string;
}

interface AuditProperties {
  actor: AuditActor;
  target: AuditTarget;
  result: "success" | "failure" | "in_review" | "denied";
  reason?: string;
  changes?: Record<string, unknown>;
}

`EyeduxEvent`

interface EyeduxEvent {
  id: string;
  environment: string;
  eyeduxType: EventEyeduxType | null;
  clientStatus: "to_check" | "solved" | "declined" | null;
  type: string;
  typeGroup: string;
  message: string | null;
  properties: Record<string, unknown>;
  status: "active" | "deleted";
  timestamp: string;
  createdAt: string;
  externalObject: EventObject | null;
  correlationObject: EventObject | null;
  metadata: Record<string, unknown> | null;
}

timestamp e createdAt são strings RFC 3339 fornecidas pela API. message será null quando o evento não tiver mensagem. A API aceita até MAX_EVENT_MESSAGE_LENGTH caracteres (500) e rejeita valores maiores com APIErrorCode.EventMessageTooLong.

const MAX_EVENT_MESSAGE_LENGTH = 500;

`RequestOptions`

interface RequestOptions {
  signal?: AbortSignal;
}

Use signal para cancelar uma chamada individual sem alterar o timeout configurado no cliente.

Diagnóstico

function currentErrorSource(sourceSkip?: number): ErrorSource | undefined;
function errorProperties(
  properties: JsonObject,
  error?: unknown,
  operation?: string,
): JsonObject;
function errorPropertiesWithSourceSkip(
  properties: JsonObject,
  error?: unknown,
  operation?: string,
  sourceSkip?: number,
): JsonObject;

Esses helpers não alteram properties. A origem é extraída do stack trace e pode variar conforme o runtime e as ferramentas de build.

Erros

`EyeduxValidationError`

Erros locais de validação, com a propriedade code:

Código	Situação
`EMPTY_API_KEY`	API key vazia
`EMPTY_PROJECT_ID`	Nenhum projeto disponível para criar o evento
`EMPTY_EXTERNAL_ID`	ID externo vazio
`INVALID_AUDIT_PROPERTIES`	Propriedades de auditoria ausentes ou inválidas

`EyeduxAPIError`

Respostas HTTP não bem-sucedidas lançam:

class EyeduxAPIError extends Error {
  statusCode: number;
  code: string;
  apiMessage: string;
  retryAfter?: number;
}

retryAfter é preenchido com o header Retry-After em segundos quando a API responde 429 com um valor inteiro.

Helper	Uso
`isAuthError(error)`	API key inválida ou revogada
`isNotFound(error)`	Evento externo não encontrado (`404`)
`isConflict(error)`	Conflito (`409`)
`isExternalObjectConflict(error)`	`external_object` duplicado
`isRateLimited(error)`	Rate limit excedido (`429`)

EyeduxRequestError representa problemas de transporte, timeout, cancelamento ou JSON de sucesso inválido. A causa original permanece em error.cause.

Contrato HTTP

Envelope de resposta

Sucessos usam o envelope abaixo:

{ "data": {} }

Erros seguem:

{
  "error": {
    "code": "event_external_object_conflict",
    "message": "external object already exists"
  }
}

Códigos conhecidos

Código	Status	Descrição
`invalid_api_key`	`422`	API key inválida ou revogada
`event_type_required`	`422`	`type` enviado vazio
`event_properties_empty`	`422`	`properties` enviado vazio
`event_message_too_long`	`422`	`message` excede 500 caracteres
`event_metric_type_invalid`	`422`	`type` inválido para um evento metric
`event_metric_property_required`	`422`	Propriedade metric obrigatória ausente
`event_metric_property_invalid`	`422`	Propriedade metric inválida
`event_external_object_conflict`	`409`	Objeto externo duplicado
`event_external_id_not_found`	`404`	ID externo não encontrado
`event_external_id_required`	`422`	ID externo vazio
`RATE_LIMIT_EXCEEDED`	`429`	Limite de requisições excedido
`INTERNAL_SERVER_ERROR`	`500`	Erro interno não mapeado

Referência da API

Base URL e autenticação

Construtores

createEyeduxClient

createEyeduxClientWithConfig

createEyeduxClientFromEnv

Métodos do cliente

createEvent

listEvents

findEventByExternalId