@asiri-ng/sdk-ts

Asiri API TypeScript SDK. A thin, fully-typed wrapper around the public Asiri HTTP API generated from openapi-public.json.

Status

The package builds to dist/ and publishes to npm from the GitHub release workflow after a PR is merged into develop, as long as the package version is not already on npm. License is UNLICENSED for now; it should become Apache-2.0 or MIT before the first public release on npm.

Install

pnpm add @asiri-ng/sdk-ts
# or
npm install @asiri-ng/sdk-ts

The SDK bundles its own openapi-fetch runtime — there are no peer dependencies.

Quickstart

import { createAsiriClient, AsiriError } from '@asiri-ng/sdk-ts';

const asiri = createAsiriClient({
  baseUrl: 'https://api.asiri.ng',
  apiKey: process.env.ASIRI_API_KEY,
});

const { data, error } = await asiri.GET('/v1/reports/overview');
if (error) {
  throw AsiriError.from(error);
}
console.log(data);

When apiKey is set, every request carries Authorization: Bearer <apiKey>. Callers can override the header on a per-request basis by passing headers to a method call.

Idempotency

Mutating requests (POST/PUT/PATCH/DELETE) require an Idempotency-Key header. The SDK does not auto-generate one — pass your own deterministic key so retries after a network failure don't double-charge:

await asiri.POST('/v1/reports/build', {
  body: { type: 'audit_summary', format: 'json' },
  headers: { 'Idempotency-Key': crypto.randomUUID() },
});

Custom fetch

Pass fetch to inject instrumentation, proxying, or test doubles:

createAsiriClient({ baseUrl, apiKey, fetch: instrumentedFetch });

Scopes

API keys carry scopes that gate which endpoints they can call. See https://docs.asiri.ng/getting-started/api-keys for the full public vocabulary (for example reports:read, reports:write, audit:read, and webhooks:write).

Errors

The Asiri API returns a uniform JSON envelope on any non-2xx response:

type AsiriErrorResponse = {
  error: {
    code: string; // machine-readable, e.g. 'invalid_api_key'
    message: string; // human-readable summary
    details?: unknown; // optional structured context
    requestId?: string; // correlate with server logs
  };
};

AsiriError.from(value, status?) parses the nested API response or the inner error object into a typed AsiriError:

class AsiriError extends Error {
  readonly code: string;
  readonly status: number | undefined;
  readonly details: unknown;
  readonly requestId: string | undefined;
}

The low-level client.GET/POST/... methods follow openapi-fetch's { data, error } convention and never throw — converting to an exception is opt-in.

Code generation

Types come from the public OpenAPI document at packages/api-client/openapi/asiri-public-api.json. The build runs:

pnpm run build
# = generate the public OpenAPI types, then compile src/ to dist/

build, typecheck, lint, test, and prepack all invoke generate first, so a fresh checkout (where src/generated/ is gitignored) just works.

Type re-exports

• paths — the canonical path-method-status map from openapi-typescript.
• components — the #/components/schemas namespace.
• operations — operation-id-keyed type map (useful for utility types).
• AsiriClient — Client<paths> from openapi-fetch, the return type of createAsiriClient.

Changelog

• 0.1.0 – Initial public surface: createAsiriClient, AsiriError, public paths/components/operations re-exports. Smoke tests cover Bearer header injection and error parsing.