Aimee TypeScript SDKs

This repo publishes two ESM TypeScript SDK packages from one npm workspace.

Packages

@aimee.shop/sdk

Public SDK for storefront and merchant-safe commerce APIs.

npm install @aimee.shop/sdk

import { AimeeSDK } from '@aimee.shop/sdk';

const sdk = new AimeeSDK({
  apiKey: process.env.AIMEE_API_KEY,
  tenantId: 'tenant-uuid',
});

const products = await sdk.products.list({ limit: 20 });
const checkout = await sdk.checkout.create({ cartId: 'cart-uuid' });

Browser usage:

import { aimee, browserAuth } from '@aimee.shop/sdk/browser';

await browserAuth.signIn('[email protected]', 'password');
const products = await aimee.products.list();

@aimee.shop/sdk-platform

Internal/admin SDK for platform operations. It includes the public SDK surface plus RBAC, payments admin, workflows, notifications, tenants, users/admin, API keys, UCP/admin, sandbox promotion, and content copy.

npm install @aimee.shop/sdk @aimee.shop/sdk-platform

import { AimeePlatformSDK } from '@aimee.shop/sdk-platform';

const sdk = new AimeePlatformSDK({
  apiKey: process.env.AIMEE_API_KEY,
  tenantId: 'tenant-uuid',
});

const roles = await sdk.rbac.roles.list();
const tenants = await sdk.tenants.list();

Development

npm install
npm run build
npm run typecheck
npm test
npm run status
npm run pack:dry-run

Quality rules:

• npm run status must pass before commit.
• No any, as any, or @ts-ignore.
• Public package must not include platform service files.
• Platform package is the only package that exposes internal/admin clients.

Authentication

Supported auth modes:

• API key for server-side consumers.
• getAccessToken for browser/framework-managed sessions.
• Cognito email/password for service-style auth.
• Interactive auth for local development.

const sdk = new AimeeSDK({
  getAccessToken: () => authContext.getToken(),
  tenantId: 'tenant-uuid',
});

Multi-Tenant Context

const tenantSdk = sdk.withTenant('other-tenant');
const storeSdk = sdk.withStore('store-uuid');

Scoped instances share authentication but get their own HTTP client so tenant/store headers are isolated.

Notification config (server / sk_ only)

List which transactional definitions exist for a store and fire a test send without placing an order. Requires a secret API key (sk_) or admin JWT with notification-config:read / notification-config:trigger, plus store context. Publishable (pk_) keys return 403. This is not on @aimee.shop/sdk/storefront. Admin template/provider work stays on @aimee.shop/sdk-platform (sdk.notifications).

sdk.setStore(storeId);
const { items } = await sdk.notificationConfig.list();
await sdk.notificationConfig.testSend({
  eventName: 'order.created',
  to: '[email protected]',
});

The live order-confirmation event is order.created (not order.confirmed).

CSV exports (server / sk_ only)

Create an async CSV export job, poll until completed, then open the presigned download URL. Requires {entity}:export (orders:export, products:export, customers:export) plus store context for store-scoped entities. Publishable (pk_) keys return 403. This is not on @aimee.shop/sdk/storefront.

sdk.setStore(storeId);
const { jobId } = await sdk.exports.create(
  { entity: 'orders', filters: { status: 'PAID' }, columnSet: 'summary' },
  { idempotencyKey: crypto.randomUUID() },
);
const job = await sdk.exports.get(jobId);
if (job.status === 'completed') {
  const { downloadUrl } = await sdk.exports.getDownloadUrl(jobId);
}

Package Boundary

Use @aimee.shop/sdk for storefronts, public developer tooling, and merchant-safe integrations.

Use @aimee.shop/sdk-platform for admin UI, internal services, and tools that need platform operations.

@aimee.shop/sdk-platform peer-depends on @aimee.shop/sdk and extends its public SDK class. Platform consumers should import SDK symbols from @aimee.shop/sdk-platform when they need the combined public plus platform surface.