SDK integration
Install and configure the server-side @alpha-explora/apicenter-sdk for APICenter shared services and payments.
@alpha-explora/apicenter-sdk is the typed Node.js client for APICenter shared services and payments. It is published to restricted GitHub Packages and requires package read access.
Install
Add this configuration to the consumer repository's .npmrc:
@alpha-explora:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=${NODE_AUTH_TOKEN}Set NODE_AUTH_TOKEN in your local environment or CI secret store to a GitHub token with package read access. Do not commit a token or paste it into source code. Install the current release:
npm install @alpha-explora/apicenter-sdk@2.0.0Configure a service
Ask an APICenter operator to register your service and issue its credentials. Keep these values in a server-only environment or secret manager. Do not use NEXT_PUBLIC_ variables or expose the service secret to a browser.
APICENTER_URL=https://api.apicenter.itsandbox.site
APICENTER_SERVICE_ID=orders-api
APICENTER_ENVIRONMENT=test
APICENTER_SERVICE_SECRET=<secret-issued-for-this-service-and-environment>Create the client in backend code:
import { ApiCenter } from '@alpha-explora/apicenter-sdk';
const api = new ApiCenter({
baseUrl: process.env.APICENTER_URL!,
auth: {
serviceId: process.env.APICENTER_SERVICE_ID!,
environment: process.env.APICENTER_ENVIRONMENT as 'test' | 'live',
secret: process.env.APICENTER_SERVICE_SECRET!,
},
});The SDK obtains and refreshes the APICenter service token. APICenter resolves the service's project and tribe from its registry entry and enforces its scopes and shared-service dependencies.
Call a shared service
Supply an idempotency key for sends and OTP mutations. Generate or persist the key for the business operation, then reuse it when retrying that same operation.
const result = await api.email.send(
{
to: 'person@example.com',
subject: 'Welcome',
text: 'Your account is ready.',
},
{ idempotencyKey: order.emailRequestKey },
);Available namespaces include email, sms, otp, geo, googleAuth, and payments. Request and response types are re-exported from @alpha-explora/apicenter-contracts.
import { randomUUID } from 'node:crypto';
const challenge = await api.otp.generate(
{ recipient: 'person@example.com', channel: 'email', purpose: 'login' },
{ idempotencyKey: randomUUID() },
);
const location = await api.geo.reverseGeocode({
latitude: 14.5995,
longitude: 120.9842,
});Payments
Use a payment API key when the platform has provisioned one. Otherwise, the service token must have the required payment scope.
APICENTER_PAYMENT_API_KEY=<optional-payment-key>const api = new ApiCenter({
baseUrl: process.env.APICENTER_URL!,
auth: {
serviceId: process.env.APICENTER_SERVICE_ID!,
environment: process.env.APICENTER_ENVIRONMENT as 'test' | 'live',
secret: process.env.APICENTER_SERVICE_SECRET!,
},
paymentApiKey: process.env.APICENTER_PAYMENT_API_KEY,
});
const checkout = await api.payments.checkouts.create(
{
referenceId: 'order-123',
amount: { amountMinor: 49900, currency: 'PHP' },
successUrl: 'https://app.example.com/payments/success',
cancelUrl: 'https://app.example.com/payments/cancel',
},
{ idempotencyKey: 'checkout-create-order-123' },
);Payment writes require a unique idempotency key between 16 and 255 characters. Persist the key with the business operation so a retry uses the same value. The SDK does not retry mutations automatically. It accepts the gateway's 202 pending-resource response as well as completed resources.
Errors
The SDK throws ApiCenterError for APICenter failures. It includes the HTTP status, APICenter code and details when present, and correlationId when the gateway returns one.
import { randomUUID } from 'node:crypto';
import { ApiCenterError } from '@alpha-explora/apicenter-sdk';
try {
await api.sms.send(
{ to: '+639171234567', message: 'Your code is ready.' },
{ idempotencyKey: randomUUID() },
);
} catch (error) {
if (error instanceof ApiCenterError) {
console.error(error.status, error.code, error.correlationId);
}
throw error;
}Choose test or live using the credentials issued for that environment. Never share credentials between services or environments.