TypeScript SDK {#overview}

npm install aliaskit

import { AliasKit } from "aliaskit";

const ak = new AliasKit();

const ak = new AliasKit({
  apiKey: "ak_live_...",
  baseUrl: "https://aliaskit.com",  // optional, defaults to production
  cardKey: "ak_ck_...",             // optional, for virtual card encryption
});

const ak = new AliasKit(); // in browser, uses session cookie

import { AliasKit } from "aliaskit";

const ak = new AliasKit();

// Create a persistent identity with a real email inbox
const identity = await ak.identities.create({
  display_name: "Checkout Agent",
  metadata: { team: "payments" },
});

// Use the identity's email to sign up on any service
await yourApp.signup(identity.email);

// Wait for the verification email to arrive
const email = await ak.emails.waitForCode(identity.id);

// The agent reads email.body_text and extracts the code
console.log(email.body_text);

// The identity persists. Reference it by ID in future runs.
const same = await ak.identities.get(identity.id);

const identity = await ak.identities.create({
  display_name: "Test Agent",
  metadata: { team: "qa", run_id: "abc-123" },
});

console.log(identity.id);    // "ident_abc123..."
console.log(identity.email); // "test-agent-abc@aliaskit.com"

const phone = await ak.identities.provisionPhone(identity.id, {
  country: "US",
});
console.log(phone.phone_number); // +1555...

const messages = await ak.identities.listMessages(identity.id);
// Returns both email and SMS messages in chronological order

const events = await ak.identities.listEvents(identity.id, {
  type: "email.received",
  limit: 50,
});

// First run: create and store the ID
const identity = await ak.identities.create({ display_name: "My Agent" });
saveToConfig(identity.id); // persist however you like

// Later runs: retrieve by ID
const id = loadFromConfig();
const identity = await ak.identities.get(id);
// Same email, same phone, same history

const email = await ak.emails.waitForCode(identity.id, {
  timeout: 60_000,
});
console.log(email.from, email.subject);
console.log(email.body_text); // agent parses the code from this

await ak.emails.send(identity.id, {
  to: "someone@example.com",
  subject: "Hello from my agent",
  body: "This is a test email sent by an AliasKit identity.",
});

const results = await ak.emails.search(identity.id, {
  query: "verification",
  from: "noreply@example.com",
});

const emails = await ak.emails.list(identity.id, {
  limit: 20,
  unread: true,
});

const email = await ak.emails.get(identity.id, emailId);
console.log(email.subject, email.from, email.body);

await ak.emails.markRead(identity.id, emailId, true);

await ak.emails.delete(identity.id, emailId);

const url = await ak.emails.getAttachmentUrl(emailId, 0);
// Returns a signed URL you can fetch directly

const sms = await ak.sms.waitForCode(identity.id, {
  timeout: 60_000,
});
console.log(sms.from, sms.body); // agent parses the code from sms.body

await ak.sms.send(identity.id, {
  to: "+15551234567",
  body: "Hello from AliasKit",
});

const messages = await ak.sms.list(identity.id, {
  limit: 10,
});

await ak.sms.markRead(identity.id, smsId, true);

await ak.sms.delete(identity.id, smsId);

const cardKey = AliasKit.generateCardKey();
// Returns: "ak_ck_..."
// Store this securely. It is irrecoverable if lost.

const ak = new AliasKit({ cardKey });

const card = await ak.cards.create(identity.id, {
  card_number: "4242424242424242",
  exp_month: 12,
  exp_year: 2028,
  cvc: "123",
  label: "Testing card",
  budget: { amount: 5000, currency: "USD", period: "monthly" },
});

// Server checks budget/status, SDK decrypts locally with your cardKey
const details = await ak.cards.reveal(card.id);
console.log(details.card_number, details.exp_month, details.cvc);

const cards = await ak.cards.list(identity.id);
// Returns metadata (label, last4, brand, status) but not plaintext details

const limits = await ak.cards.budget(card.id);
console.log(limits.amount, limits.currency, limits.period);

await ak.cards.updateBudget(card.id, {
  amount: 10000,
  period: "monthly",
});

const txns = await ak.cards.activity(card.id);

await ak.cards.freeze(card.id);     // temporarily disable
await ak.cards.unfreeze(card.id);   // re-enable a frozen card
await ak.cards.cancel(card.id);     // permanent, cannot be undone

const totp = await ak.totp.register(identity.id, {
  secret: "JBSWY3DPEHPK3PXP",
  serviceName: "MyApp",
  algorithm: "SHA1",
  digits: 6,
  period: 30,
});

const { code, remaining_seconds } = await ak.totp.getCode(identity.id, totp.id);
console.log(`Code: ${code}, expires in ${remaining_seconds}s`);

const entries = await ak.totp.list(identity.id);

await ak.totp.delete(identity.id, totpId);

const sub = ak.realtime.subscribeToEmails(identity.id, (email) => {
  console.log("New email from:", email.from);
  console.log("Subject:", email.subject);
});

// Subscribe to SMS
const smsSub = ak.realtime.subscribeToSms(identity.id, (sms) => {
  console.log("SMS from:", sms.from, sms.body);
});

// Subscribe to all events
const allSub = ak.realtime.subscribe(identity.id, (event) => {
  console.log("Event:", event.type, event.data);
});

// Clean up when done
sub.unsubscribe();
smsSub.unsubscribe();
allSub.unsubscribe();

const sub = await ak.billing.getSubscription();
console.log(sub.plan, sub.status);

const sub = await ak.billing.getSubscription();
console.log(sub.plan, sub.status);

const key = await ak.apiKeys.create({
  label: "CI pipeline",
  scopes: ["identities:write", "emails:read"],
});
console.log(key.key); // ak_live_... (shown only once, store it)

// List existing keys
const keys = await ak.apiKeys.list();

// Revoke when no longer needed
await ak.apiKeys.revoke(key.id);

const webhook = await ak.webhooks.create({
  url: "https://your-app.com/webhooks/aliaskit",
  secret: "whsec_...",
  events: ["email.received", "sms.received", "identity.created"],
  active: true,
});

await ak.webhooks.update(webhook.id, {
  events: ["email.received", "sms.received"],
  active: false,
});

const deliveries = await ak.webhooks.deliveries(webhook.id, {
  limit: 20,
});

app.post("/webhooks/aliaskit", (req, res) => {
  const signature = req.headers["x-aliaskit-signature"];
  const valid = ak.webhooks.verify(req.body, signature, "whsec_...");

  if (!valid) return res.status(401).send("Invalid signature");

  // Process the event
  console.log(req.body.event, req.body.data);
  res.sendStatus(200);
});

const domain = await ak.domains.add("agents.yourcompany.com");
// Configure DNS records shown in domain.dns_records (MX, SPF, DKIM)

// After configuring DNS, verify:
const verified = await ak.domains.verify(domain.id);
console.log(verified.status); // "verified" or "pending"

// List all domains
const domains = await ak.domains.list();

// Remove a domain
await ak.domains.delete(domain.id);

import {
  AliasKitError,
  EmailTimeoutError,
} from "aliaskit";

import {
  AliasKit,
  encryptCard,
  decryptCard,
  extractCardMeta,
} from "aliaskit";

const cardKey = AliasKit.generateCardKey();
// "ak_ck_..."

const encrypted = encryptCard({
  card_number: "4242424242424242",
  exp_month: 12,
  exp_year: 2028,
  cvc: "123",
}, cardKey);

const plaintext = decryptCard(encrypted, cardKey);
console.log(plaintext.card_number, plaintext.cvc);

const meta = extractCardMeta({
  card_number: "4242424242424242",
  exp_month: 12,
  exp_year: 2028,
});
// { last4: "4242", brand: "visa", expiry: "12/2028" }