SDK quickstart

Install the SDK, authenticate, deploy an application, and clean up — end to end.

1. Install

npm install @edgible-team/sdk

Not yet published to npm — until the first 0.x release, install from the repo checkout (npm install <path-to>/sdk) or npm link it.

Requires Node 20+ (browser builds are also supported — see Tiers & entry points).

2. Authenticate

import { createClient } from '@edgible-team/sdk';

const client = createClient({
  env: 'prod', // 'dev' | 'test' | 'uat' | 'prod' — default: EDGIBLE_ENV, else 'prod'
  credentials: { type: 'password', email: 'you@example.com', password: process.env.EDGIBLE_PASSWORD! },
});

const me = await client.auth.me();
const organizationId = me.organizations[0]!;

On Node, createClient() with no credentials reuses an existing edgible CLI login session automatically. See Authentication & credentials.

3. Deploy an application

Write a stack file (edgible.yml) next to a compose file. It targets one of your registered serving devices (client.organizations.listDevices({ organizationId }) to find one):

apiVersion: v3
kind: Application
metadata:
  name: hello-edgible
spec:
  placement:
    strategy: serving-device
    deviceSelector: { deviceName: my-device }
  workloads:
    - name: web
      type: compose
      composeFile: ./compose.yml   # e.g. an nginx:alpine service exposing port 80
      ports:
        - { name: http, containerPort: 80, protocol: tcp }
  access:
    - name: web
      type: https
      target: { workload: web, port: http }
      hostname: { generated: true }
      tls: { managedBy: edgible }

Load it and deploy — stacks.deploy is create-or-update, so re-running converges instead of duplicating:

import { loadStackFile } from '@edgible-team/sdk/node';

const { applications: documents } = loadStackFile('./edgible.yml', { organization: organizationId });
const result = await client.stacks.deploy({ documents, organizationId });
if (!result.success) throw new Error(JSON.stringify(result.failed));
const { applicationId } = result.deployed[0]!;

4. Wait until it’s ready

Poll the deployment state machine: 'ready' is success; 'error' and 'degraded' are terminal failures.

let state: string;
do {
  await new Promise((r) => setTimeout(r, 5_000));
  ({ state } = await client.applications.getDeploymentStatus(applicationId));
  console.log(`deployment state: ${state}`);
} while (state !== 'ready' && state !== 'error' && state !== 'degraded');

(For a single existing application, client.applications.deploy(...) returns an Operation with a built-in waitUntilReady() waiter that does this for you — see Long-running operations.)

5. Check it and clean up

const reachability = await client.applications.checkReachability(applicationId);
console.log(`reachable: ${reachability.reachable}`);

await client.stacks.teardown({ documents, organizationId });

Next steps

• Tiers & entry points — which import runs where.
• Long-running operations — waiters and progress callbacks.
• Idempotency & safe re-runs — what happens when a deploy script runs twice.