xaqiiji-sdk

Official JavaScript/TypeScript SDK for the Xaqiiji identity verification API.

Works in Node.js 18+ and any runtime with fetch (Deno, Bun, edge workers).

Monorepo: This package is published from the xaqiiji-sdk/ folder inside ahmed-dalab/xaqiiji. Integration docs: docs.xaqiiji.ahmed-dalab.com.

Install

npm install xaqiiji-sdk

Quick start

import { Xaqiiji } from 'xaqiiji-sdk';

const client = new Xaqiiji({
  apiKey: process.env.XAQIIJI_API_KEY!, // xq_live_... or xq_test_...
  environment: 'live',
});

const result = await client.verify.citizen({
  nationalId: '12345678901', // 11 digits
  purpose: 'pre_employment',
});

console.log(result.result, result.reference, result.citizen?.fullName);

Configuration

| Option | Default | Description | |--------|---------|-------------| | apiKey | — | Business API key (xq_live_ / xq_test_) | | environment | 'live' | Key tier; both use the same API host | | baseUrl | https://api.xaqiiji.ahmed-dalab.com | API origin (no trailing slash) | | timeout | 10000 | Request timeout (ms) | | maxRetries | 2 | Retries on HTTP 503 |

Override the host for staging or self-hosted deployments:

const client = new Xaqiiji({
  apiKey: process.env.XAQIIJI_API_KEY!,
  baseUrl: 'https://api.xaqiiji.ahmed-dalab.com',
});

API coverage

Works with an enterprise API key (xq_test_* / xq_live_*)

| SDK call | API endpoint | |----------|----------------| | client.verify.citizen() | POST /api/v1/verify/citizen | | client.verify.list() | GET /api/v1/verifications | | client.billing.getBalance() | GET /api/v1/billing/balance | | client.billing.listTransactions() | GET /api/v1/billing/transactions | | client.billing.listPackages() | GET /api/v1/billing/packages (public, no key) |

Authentication uses Authorization: Bearer <api_key>.

Credits: Both test and live keys deduct credits on successful verifications (except service_unavailable and cached/idempotent replays). Ensure the business has credits before calling verify.

Requirements: Business must be approved, active, and on the Enterprise plan.

Portal session only

| SDK call | Why | |----------|-----| | client.keys.* | Create/revoke keys in Developer → API keys (JWT) | | client.billing.createStripeCheckout() | Purchases need a logged-in business admin |

client.keys.create() throws XaqiijiPortalSessionError — use the portal to create your first API key, then pass it to the SDK.

Error handling

import {
  XaqiijiInsufficientCreditsError,
  XaqiijiInvalidFormatError,
  XaqiijiAuthError,
} from 'xaqiiji-sdk';

try {
  await client.verify.citizen({ nationalId: '12345678901', purpose: 'other' });
} catch (err) {
  if (err instanceof XaqiijiInsufficientCreditsError) {
    // redirect user to top-up
  }
}

Development

cd xaqiiji-sdk
npm install
npm run build
npm run typecheck

Live integration test

Create an API key in the portal, then:

cp .env.example .env
# edit .env with your key

export $(grep -v '^#' .env | xargs)
npm run test:live

Health endpoint (no auth): GET https://api.xaqiiji.ahmed-dalab.com/api/health

Example script

XAQIIJI_API_KEY=xq_test_... npx tsx examples/verify-citizen.ts

Publish to npm

npm login
npm publish

Bump version in package.json before each release.

License

MIT