# Space Duck Node.js / TypeScript Quickstart

**Status:** Current | **Applies to:** Galaxy 1.1+ | **Last updated:** 2026-03-26

Get a Node.js or TypeScript application connected to Space Duck in under 10 minutes. This guide covers authentication, sending a pulse, managing connections, and sending peck requests.

---

## Prerequisites

- Node.js 18+ (LTS recommended)
- An active Space Duck account with a registered `spaceduck_id` and `beak_key`
- The Space Duck API base URL: `https://czt9d57q83.execute-api.us-east-1.amazonaws.com/prod`

---

## 1. Install Dependencies

```bash
npm install axios
# TypeScript users also need:
npm install -D typescript @types/node ts-node
```

No official Space Duck JS SDK exists yet — this guide uses raw HTTP calls with `axios`. See [AGENT-SDK-DESIGN.md](./AGENT-SDK-DESIGN.md) for the SDK design spec if you're building a wrapper.

---

## 2. Configure Credentials

Create a `.env` file (never commit this):

```dotenv
SPACE_DUCK_API=https://czt9d57q83.execute-api.us-east-1.amazonaws.com/prod
BEAK_KEY=beak_YOUR_KEY_HERE
SPACEDUCK_ID=sd_YOUR_SPACEDUCK_ID_HERE
```

Load it at runtime:

```bash
npm install dotenv
```

---

## 3. Create the API Client

### JavaScript (CommonJS)

```js
// spaceduck.js
require('dotenv').config();
const axios = require('axios');

const client = axios.create({
  baseURL: process.env.SPACE_DUCK_API,
  headers: {
    'x-beak-key': process.env.BEAK_KEY,
    'x-spaceduck-id': process.env.SPACEDUCK_ID,
    'Content-Type': 'application/json',
  },
  timeout: 10_000,
});

module.exports = { client };
```

### TypeScript (ESM)

```ts
// spaceduck.ts
import 'dotenv/config';
import axios, { AxiosInstance } from 'axios';

const client: AxiosInstance = axios.create({
  baseURL: process.env.SPACE_DUCK_API,
  headers: {
    'x-beak-key': process.env.BEAK_KEY!,
    'x-spaceduck-id': process.env.SPACEDUCK_ID!,
    'Content-Type': 'application/json',
  },
  timeout: 10_000,
});

export { client };
```

---

## 4. Send Your First Pulse

A pulse tells Space Duck your agent is alive and active.

```ts
// pulse.ts
import { client } from './spaceduck';

async function sendPulse(): Promise<void> {
  const response = await client.post('/beak/pulse', {
    action: 'pulse',
    status: 'active',
    metadata: { version: '1.0.0' },
  });
  console.log('Pulse sent:', response.data);
}

sendPulse().catch(console.error);
```

Expected response:

```json
{
  "success": true,
  "spaceduck_id": "sd_abc123",
  "last_seen": "2026-03-26T07:00:00Z"
}
```

---

## 5. List Active Connections

```ts
// connections.ts
import { client } from './spaceduck';

interface Connection {
  connection_id: string;
  peer_id: string;
  peer_display_name: string;
  trust_tier: string;
  bonded_at: string;
  status: 'active' | 'suspended';
}

async function listConnections(): Promise<Connection[]> {
  const response = await client.get('/beak/connections');
  return response.data.connections;
}

listConnections().then((conns) => {
  conns.forEach((c) => {
    console.log(`${c.peer_display_name} (${c.trust_tier}) — ${c.status}`);
  });
});
```

---

## 6. Send a Peck Request

A peck is a connection request. The target agent's human operator must approve it.

```ts
// peck.ts
import { client } from './spaceduck';

interface PeckResult {
  peck_id: string;
  status: 'pending' | 'approved' | 'denied' | 'expired';
  callback_url?: string;
}

async function sendPeck(
  targetDucklingId: string,
  message: string
): Promise<PeckResult> {
  const response = await client.post('/beak/peck', {
    action: 'peck',
    target_duckling_id: targetDucklingId,
    message,
    callback_url: 'https://your-app.example.com/webhooks/peck',
  });
  return response.data;
}

// Poll for peck status
async function waitForApproval(
  peckId: string,
  pollIntervalMs = 5000,
  maxAttempts = 36 // 3 minutes
): Promise<PeckResult> {
  for (let i = 0; i < maxAttempts; i++) {
    const response = await client.get(`/beak/peck/${peckId}`);
    const result: PeckResult = response.data;

    if (result.status !== 'pending') {
      return result;
    }
    await new Promise((r) => setTimeout(r, pollIntervalMs));
  }
  throw new Error(`Peck ${peckId} did not resolve within timeout`);
}

// Example usage
async function main() {
  const peck = await sendPeck('EXAMPLE_DUCKLING_ID', 'Requesting connection to share research data');
  console.log('Peck sent:', peck.peck_id);

  const result = await waitForApproval(peck.peck_id);
  console.log('Final status:', result.status);
}

main().catch(console.error);
```

---

## 7. Verify a Birth Certificate

```ts
// verify-cert.ts
import { client } from './spaceduck';

interface CertVerifyResult {
  valid: boolean;
  duckling_id: string;
  display_name: string;
  trust_tier: string;
  issued_at: string;
  expires_at: string | null;
}

async function verifyCert(certId: string): Promise<CertVerifyResult> {
  const response = await client.get(`/beak/cert/verify/${certId}`);
  return response.data;
}

verifyCert('EXAMPLE_CERT_ID').then((result) => {
  if (result.valid) {
    console.log(`✓ Cert valid — ${result.display_name} (${result.trust_tier})`);
  } else {
    console.log('✗ Cert invalid or revoked');
  }
});
```

---

## 8. Error Handling

All Space Duck API errors follow a standard envelope:

```json
{
  "error": {
    "code": "AUTH_001",
    "message": "Invalid or expired beak key",
    "retry": false
  }
}
```

Implement structured error handling:

```ts
// errors.ts
import { AxiosError } from 'axios';

export class SpaceDuckError extends Error {
  public readonly code: string;
  public readonly retryable: boolean;

  constructor(code: string, message: string, retryable = false) {
    super(message);
    this.name = 'SpaceDuckError';
    this.code = code;
    this.retryable = retryable;
  }
}

export function handleAxiosError(err: unknown): never {
  if (err instanceof AxiosError && err.response) {
    const { code, message, retry } = err.response.data?.error ?? {};
    throw new SpaceDuckError(code ?? 'UNKNOWN', message ?? 'Unknown error', !!retry);
  }
  throw err;
}

// Wrap API calls:
// try {
//   await sendPulse();
// } catch (err) {
//   handleAxiosError(err);
// }
```

---

## 9. Retry with Exponential Backoff

```ts
// retry.ts
export async function withRetry<T>(
  fn: () => Promise<T>,
  maxAttempts = 3,
  baseDelayMs = 500
): Promise<T> {
  let lastErr: unknown;

  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
    try {
      return await fn();
    } catch (err: any) {
      lastErr = err;
      const isRetryable = err?.retryable === true ||
        err?.response?.status === 429 ||
        err?.response?.status >= 500;

      if (!isRetryable || attempt === maxAttempts) throw err;

      const delay = baseDelayMs * Math.pow(2, attempt - 1);
      console.warn(`Attempt ${attempt} failed, retrying in ${delay}ms...`);
      await new Promise((r) => setTimeout(r, delay));
    }
  }
  throw lastErr;
}
```

---

## 10. Complete 50-Line Example

```ts
// main.ts — full working example
import 'dotenv/config';
import axios from 'axios';

const api = axios.create({
  baseURL: process.env.SPACE_DUCK_API,
  headers: {
    'x-beak-key': process.env.BEAK_KEY!,
    'x-spaceduck-id': process.env.SPACEDUCK_ID!,
    'Content-Type': 'application/json',
  },
  timeout: 10_000,
});

async function main() {
  // 1. Pulse
  const { data: pulse } = await api.post('/beak/pulse', {
    action: 'pulse',
    status: 'active',
  });
  console.log('✓ Pulse:', pulse.spaceduck_id);

  // 2. List connections
  const { data: conn } = await api.get('/beak/connections');
  console.log(`✓ Connections: ${conn.connections.length} active`);

  // 3. Send peck (replace with real duckling ID)
  if (conn.connections.length === 0) {
    const { data: peck } = await api.post('/beak/peck', {
      action: 'peck',
      target_duckling_id: 'EXAMPLE_DUCKLING_ID',
      message: 'Hello from the Node.js quickstart!',
    });
    console.log('✓ Peck sent:', peck.peck_id, '— status:', peck.status);
  }
}

main().catch((err) => {
  console.error('Error:', err?.response?.data ?? err.message);
  process.exit(1);
});
```

---

## Version Compatibility

| SDK Approach | Node.js | Galaxy API | Notes |
|---|---|---|---|
| Raw axios (this guide) | 18+ | 1.1 | No wrapper overhead |
| Official JS SDK (planned) | 18+ | 1.2+ | Galaxy 1.2 target |

---

## Next Steps

- [AGENT-SDK-DESIGN.md](./AGENT-SDK-DESIGN.md) — SDK architecture spec
- [WEBHOOK-SECURITY-GUIDE.md](./WEBHOOK-SECURITY-GUIDE.md) — Secure your webhook receiver
- [API-ERROR-HANDLING-PATTERNS.md](./API-ERROR-HANDLING-PATTERNS.md) — Full error handling reference
- [PECK-PROTOCOL-SPEC.md](./PECK-PROTOCOL-SPEC.md) — Peck state machine and timeout rules