Integration quickstart

curl --silent --show-error 'https://aegis-api.theauroraedge.com/v1/intakes' \
  -H "Authorization: Bearer $AEGIS_API_KEY"

curl --silent --show-error 'https://aegis-api.theauroraedge.com/v1/login-sessions' \
  -H "Authorization: Bearer $AEGIS_API_KEY" -H 'Content-Type: application/json' \
  --data '{"email":"cfo@acme.example","companyName":"Acme Partner FZ-LLC","externalRef":"ORDER-88213","labelId":"corporate","redirectPath":"/dashboard"}'

# Current owner. To select a member, add "email":"legal@acme.example" to the body.
curl --silent --show-error "https://aegis-api.theauroraedge.com/v1/applications/$CLIENT_ID/login-sessions" \
  -H "Authorization: Bearer $AEGIS_API_KEY" -H 'Content-Type: application/json' \
  --data '{"redirectPath":"/dashboard"}'

# Add membership. Save uid from this response.
curl --silent --show-error "https://aegis-api.theauroraedge.com/v1/applications/$CLIENT_ID/members" \
  -H "Authorization: Bearer $AEGIS_API_KEY" -H 'Content-Type: application/json' \
  --data '{"email":"legal@acme.example"}'

# Issue the invitation link only after membership succeeds.
curl --silent --show-error "https://aegis-api.theauroraedge.com/v1/applications/$CLIENT_ID/login-sessions" \
  -H "Authorization: Bearer $AEGIS_API_KEY" -H 'Content-Type: application/json' \
  --data '{"email":"legal@acme.example","redirectPath":"/dashboard"}'

# MEMBER_UID is the uid of the teammate being removed.
curl --silent --show-error -X DELETE \
  "https://aegis-api.theauroraedge.com/v1/applications/$CLIENT_ID/members/$MEMBER_UID" \
  -H "Authorization: Bearer $AEGIS_API_KEY"

await aegis.removeMember(clientId, currentOwnerUid, replacementMemberUid);
// The helper sends ?newOwnerUid=<replacementMemberUid> with DELETE.
// Future issueLink(clientId) calls target the replacement owner.

# One application, including status, latest decision and members.
curl --silent --show-error "https://aegis-api.theauroraedge.com/v1/applications/$CLIENT_ID" \
  -H "Authorization: Bearer $AEGIS_API_KEY"

# First page. Continue using nextCursor while hasMore is true.
curl --silent --show-error --get 'https://aegis-api.theauroraedge.com/v1/applications' \
  -H "Authorization: Bearer $AEGIS_API_KEY" --data-urlencode 'limit=100'

# Next page, with CURSOR set to the exact nextCursor from the previous response.
curl --silent --show-error --get 'https://aegis-api.theauroraedge.com/v1/applications' \
  -H "Authorization: Bearer $AEGIS_API_KEY" --data-urlencode 'limit=100' --data-urlencode "cursor=$CURSOR"

curl --silent --show-error 'https://aegis-api.theauroraedge.com/v1/webhooks' \
  -H "Authorization: Bearer $AEGIS_API_KEY" -H 'Content-Type: application/json' \
  --data '{"url":"https://integrations.example.com/aegis/events","events":["application.submitted","application.status.changed","application.info_request.raised"],"description":"Onboarding updates"}'

# After securely configuring the receiver with the returned secret:
curl --silent --show-error "https://aegis-api.theauroraedge.com/v1/webhooks/$ENDPOINT_ID/test" \
  -H "Authorization: Bearer $AEGIS_API_KEY" -H 'Content-Type: application/json' --data '{}'

curl --silent --show-error -X PATCH "https://aegis-api.theauroraedge.com/v1/webhooks/$ENDPOINT_ID" \
  -H "Authorization: Bearer $AEGIS_API_KEY" -H 'Content-Type: application/json' \
  --data '{"url":"https://integrations.example.com/aegis/events-v2","events":["application.submitted","application.status.changed","application.info_request.raised","application.info_request.answered"]}'

import { createHmac, timingSafeEqual } from 'node:crypto';

// acceptEvent must atomically deduplicate and durably queue the event.
// Resolve only after commit, including for an already accepted duplicate.
export function createWebhookHandler({ tenantId, secrets, acceptEvent }) {
  if (!tenantId || !Array.isArray(secrets) || !secrets.length ||
      secrets.some(secret => typeof secret !== 'string' || !secret) ||
      typeof acceptEvent !== 'function') throw new Error('Configure tenant, secrets and durable acceptance');
  return async function handleWebhook(rawBody, headers) {
    // headers is a standard Headers object. rawBody is the original Buffer.
    const timestamp = headers.get('Aegis-Webhook-Timestamp');
    if (!Buffer.isBuffer(rawBody) || !/^\d+$/.test(timestamp ?? '')) return { status: 401 };
    const seconds = Number(timestamp);
    if (!Number.isSafeInteger(seconds) || Math.abs(Date.now() / 1000 - seconds) > 300) {
      return { status: 401 };
    }
    const signatures = (headers.get('Aegis-Webhook-Signature') ?? '').split(/\s+/)
      .filter(value => /^v1=[0-9a-f]{64}$/.test(value))
      .map(value => Buffer.from(value.slice(3), 'hex'));
    const valid = secrets.some(secret => {
      const digest = createHmac('sha256', secret)
        .update(timestamp + '.', 'utf8').update(rawBody).digest();
      return signatures.some(signature => timingSafeEqual(signature, digest));
    });
    if (!valid) return { status: 401 };

    let event;
    try { event = JSON.parse(rawBody.toString('utf8')); } catch { return { status: 400 }; }
    if (!event || typeof event.id !== 'string' || !event.id ||
        typeof event.type !== 'string' || !event.type ||
        event.tenantId !== tenantId ||
        event.id !== headers.get('Aegis-Webhook-Id') ||
        event.type !== headers.get('Aegis-Webhook-Event')) return { status: 400 };
    if (event.type.startsWith('application.') &&
        (typeof event.data?.clientId !== 'string' || !event.data.clientId)) return { status: 400 };
    try {
      await acceptEvent(event);
      return { status: 204 };
    } catch {
      return { status: 503 }; // No acknowledgement when durable acceptance fails.
    }
  };
}

// Call this from your durable queue worker. Retry the job if processing throws.
export function createReconciler({ aegis, withApplicationLock, saveApplication }) {
  return async function reconcile(event) {
    if (!event.type.startsWith('application.')) return; // Includes webhook.test.
    const clientId = event.data.clientId;
    await withApplicationLock(event.tenantId + ':' + clientId, async () => {
      const application = await aegis.getApplication(clientId);
      await saveApplication(application);
    });
  };
}

curl --silent --show-error "https://aegis-api.theauroraedge.com/v1/applications/$CLIENT_ID/info-requests" \
  -H "Authorization: Bearer $AEGIS_API_KEY"

curl --silent --show-error "https://aegis-api.theauroraedge.com/v1/applications/$CLIENT_ID/login-sessions" \
  -H "Authorization: Bearer $AEGIS_API_KEY" -H 'Content-Type: application/json' \
  --data '{"redirectPath":"/requests"}'

export function createAegisClient(apiKey) {
  if (!apiKey) throw new Error('Set AEGIS_API_KEY on your server');
  const base = 'https://aegis-api.theauroraedge.com';
  const id = value => encodeURIComponent(value);
  const applicationPath = clientId => '/v1/applications/' + id(clientId);

  async function request(path, method = 'GET', body) {
    const response = await fetch(base + path, {
      method,
      headers: {
        Authorization: 'Bearer ' + apiKey,
        ...(body === undefined ? {} : { 'Content-Type': 'application/json' })
      },
      body: body === undefined ? undefined : JSON.stringify(body),
      signal: AbortSignal.timeout(30000)
    });
    const text = response.status === 204 ? '' : await response.text();
    let data = null;
    try { data = text ? JSON.parse(text) : null; } catch { /* proxy response */ }
    if (!response.ok) {
      const error = new Error('Aegis request failed');
      Object.assign(error, {
        status: response.status,
        code: data?.error?.code,
        details: data?.error?.details,
        requestId: response.headers.get('Aegis-Request-Id') ?? data?.error?.requestId,
        retryAfter: response.headers.get('Retry-After')
      });
      throw error;
    }
    if (response.status !== 204 && data === null) throw new Error('Invalid Aegis response');
    return data;
  }

  const issueLink = (clientId, email, redirectPath = '/dashboard') =>
    request(applicationPath(clientId) + '/login-sessions', 'POST', {
      ...(email === undefined ? {} : { email }), redirectPath
    });
  const addMember = (clientId, email) =>
    request(applicationPath(clientId) + '/members', 'POST', { email });

  return {
    listIntakes: () => request('/v1/intakes'),
    createApplicationWithLink: fields => request('/v1/login-sessions', 'POST', fields),
    getApplication: clientId => request(applicationPath(clientId)),
    issueLink,
    addMember,
    async inviteMember(clientId, email) {
      const member = await addMember(clientId, email);
      const session = await issueLink(clientId, email);
      return { member, ...session };
    },
    removeMember(clientId, uid, newOwnerUid) {
      const query = newOwnerUid === undefined ? '' :
        '?' + new URLSearchParams({ newOwnerUid });
      return request(applicationPath(clientId) + '/members/' + id(uid) + query, 'DELETE');
    },
    async *listApplications(filters = {}) {
      const query = new URLSearchParams({ limit: '100', ...filters });
      query.delete('cursor');
      const seen = new Set();
      const cursors = new Set();
      while (true) {
        const page = await request('/v1/applications?' + query);
        if (!Array.isArray(page?.data) || typeof page.hasMore !== 'boolean') {
          throw new Error('Invalid application page');
        }
        for (const application of page.data) {
          if (typeof application?.clientId !== 'string' || !application.clientId) {
            throw new Error('Invalid application identifier');
          }
          if (!seen.has(application.clientId)) {
            seen.add(application.clientId);
            yield application;
          }
        }
        if (!page.hasMore) return;
        if (typeof page.nextCursor !== 'string' || !page.nextCursor || cursors.has(page.nextCursor)) {
          throw new Error('Invalid or repeated application cursor');
        }
        cursors.add(page.nextCursor);
        query.set('cursor', page.nextCursor);
      }
    },
    getInfoRequests: clientId => request(applicationPath(clientId) + '/info-requests'),
    listWebhooks: () => request('/v1/webhooks'),
    registerWebhook: fields => request('/v1/webhooks', 'POST', fields),
    updateWebhook: (endpointId, fields) => request('/v1/webhooks/' + id(endpointId), 'PATCH', fields),
    testWebhook: endpointId => request('/v1/webhooks/' + id(endpointId) + '/test', 'POST', {})
  };
}