Skip to main content

Documentation Index

Fetch the complete documentation index at: https://archie.com/docs/llms.txt

Use this file to discover all available pages before exploring further.

When you need to talk to a service Archie does not provide a built-in for, build a custom integration. This page covers the developer workflow.

​
Workflow

  1. Add to the blueprint — open the Integrations card and add a custom integration with a clear description of its purpose
  2. Run the build — the generator scaffolds an integration module
  3. Implement the client — fill in HTTP requests in the generated client wrapper
  4. Configure credentials — store API keys or OAuth tokens in the integration settings
  5. Add webhook handlers — if the service pushes events to you

​
Generated scaffolding

A custom integration produces:
  • integrations/<name>/client.ts — typed wrapper with placeholder methods
  • integrations/<name>/config.ts — credential schema (what fields you store)
  • api/webhooks/<name>/route.ts — webhook receiver (if your description mentioned receiving events)
  • A registration entry so the integration appears in the App services → Integrations UI

​
Implementing the client

Replace placeholder methods with real HTTP calls. Use the integration’s auth pattern — Bearer token, OAuth, signed request, mTLS. 
export class MyServiceClient {
  constructor(private config: MyServiceConfig) {}

  async sendEvent(event: Event) {
    const res = await fetch(`${this.config.baseUrl}/events`, {
      method: "POST",
      headers: {
        "Authorization": `Bearer ${this.config.apiKey}`,
        "Content-Type": "application/json",
      },
      body: JSON.stringify(event),
    })
    if (!res.ok) throw new Error(`MyService error: ${res.status}`)
    return res.json()
  }
}

​
OAuth-based integrations

For OAuth, the workflow includes:
  • An install flow that redirects users to the third-party authorization page
  • A callback route that exchanges the authorization code for tokens
  • Token storage and refresh
Archie’s OAuth helpers handle the flow scaffolding.

​
Webhook handlers

The generated webhook route verifies signatures. You implement the event handling — typically by dispatching to a custom function so the receiver can acknowledge the delivery quickly while the work runs in the background: 
export async function handler(req: Request, ctx: Context) {
  const event = await req.json()
  switch (event.type) {
    case "payment.succeeded":
      // your logic
      break
  }
  return new Response("ok")
}

​
Publishing and reuse

Custom integrations are project-scoped. To reuse across projects in your workspace, package the client as a workspace shared module.

​
FAQ

Use a tunnel (ngrok, cloudflared) to expose your local dev server, or test against the preview environment.