# Macro Inc. Example Projects: A Complete Guide to the Official SDK and Rust Samples

> Explore Macro Inc. example projects in TypeScript and Rust. Discover webhook handling, message streaming, push notifications, and service integrations with the official SDK and samples.

- Repository: [Macro/macro](https://github.com/macro-inc/macro)
- Tags: getting-started
- Published: 2026-08-20

---

**Macro Inc. ships production-ready example projects across TypeScript and Rust that demonstrate webhook handling, message streaming, push notifications, and service integrations.**

Macro Inc. is a modular productivity platform built on independent services for Email, Channels, Documents, Tasks, Agents, Calls, and CRM. Whether you're building client automations or backend integrations, the official `macro-inc/macro` repository contains **stand-alone example projects** that show exactly how to work with each component. This guide walks through where to find these samples, what they demonstrate, and how to run them.

## TypeScript SDK Examples for Client-Side Integration

The **TypeScript SDK** (`packages/sdk`) wraps Macro's HTTP APIs and provides a type-safe interface for building agents, automations, and webhook listeners. All SDK examples live in `packages/sdk/examples/` and can be executed directly with Bun after setting `MACRO_BOT_TOKEN`.

### Register and Log All Webhook Events

The [`webhook-events.ts`](https://github.com/macro-inc/macro/blob/main/webhook-events.ts) example demonstrates the complete flow for receiving real-time events from Macro. It registers a webhook for every available event type, spins up a local HTTP server, and logs incoming payloads with signature verification.

```typescript
// packages/sdk/examples/webhook-events.ts
import type { Env } from '../src/config';
import type { EventName } from '../src/events/types';
import { Macro } from '../src/macro';

const [url, actAs] = process.argv.slice(2);
const botToken = process.env.MACRO_BOT_TOKEN;

if (!url || !actAs || !botToken) {
  console.error(
    'usage: MACRO_BOT_TOKEN=mbot_... bun examples/webhook-events.ts <public-url> <acting-user-id>',
  );
  process.exit(1);
}

const env = (process.env.MACRO_ENV ?? 'dev') as Env;
const bot = new Macro({ env, auth: { type: 'bot', token: botToken } });
const macro = bot.requestedAs(bot.users.byId(actAs));

const ALL_EVENTS = [
  'channel.created',
  'channel.deleted',
  // … (full list in the file)
] as const satisfies readonly EventName[];

let receiver: ((req: Request) => Promise<Response>) | null = null;

// Serve the webhook endpoint
Bun.serve({
  port: Number(process.env.PORT ?? 8787),
  async fetch(req) {
    if (!receiver) return new Response('ok');
    try { return await receiver(req); }
    catch (e) { console.error('[bad signature]', e); return new Response('invalid signature', { status: 401 }); }
  },
});

const webhook = await macro.webhooks.create({
  url,
  namespace: `sdk-webhook-demo-${crypto.randomUUID()}`,
  name: 'sdk webhook demo',
  filters: [{ events: [...ALL_EVENTS] }],
});

const secret = webhook.signingSecret;
if (!secret) throw new Error('webhook registered but no signing secret returned');

const events = new Macro({
  env,
  auth: { type: 'bot', token: botToken },
  webhookSecret: secret,
}).events;

// Log each event as it arrives
for (const name of ALL_EVENTS) {
  events.on(name, (event) => console.log(name, event.metadata));
}

// Wire the webhook handler
receiver = events.webhook();

```

Additional SDK examples include:
- **[`doc-dump.ts`](https://github.com/macro-inc/macro/blob/main/doc-dump.ts)** — Dumps all documents accessible to the bot for quick inspection
- **[`channel-webhook.ts`](https://github.com/macro-inc/macro/blob/main/channel-webhook.ts)** — Minimal webhook that filters only for `channel.*` events
- **[`channel-probe.ts`](https://github.com/macro-inc/macro/blob/main/channel-probe.ts)** — Retrieves current channel state, participant list, and metadata

## Rust Crate Examples for Backend Streaming

Macro's core services are written in Rust, and the **service client crates** expose streaming consumers for building reactive backends. These examples use `tokio` and demonstrate how to subscribe to live event streams via the internal message bus (SQS/Lambda).

### Stream Channel Messages in Real Time

The [`channels_consumer.rs`](https://github.com/macro-inc/macro/blob/main/channels_consumer.rs) example in `crates/channels/examples/` shows how to consume a live stream of messages from a specific channel:

```rust
// crates/channels/examples/channels_consumer.rs
use macro_channels_service_client::ChannelsClient;
use macro_channels_service_client::types::ChannelMessage;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    // Initialise a client that talks to the running local service
    let client = ChannelsClient::new_from_env()?;

    // Subscribe to all message events for a specific channel
    let mut stream = client
        .stream_channel_messages("channel-123")
        .await?
        .filter_map(|msg| async move { msg.ok() });

    // Process each incoming message
    while let Some(message) = stream.next().await {
        println!("New message from {}: {}", message.author_id, message.content);
    }

    Ok(())
}

```

Other critical Rust consumer examples:
- **[`documents_consumer.rs`](https://github.com/macro-inc/macro/blob/main/documents_consumer.rs)** — Streams document creation, update, and deletion events
- **[`projects_consumer.rs`](https://github.com/macro-inc/macro/blob/main/projects_consumer.rs)** — Consumes project-wide activity and lifecycle events
- **[`basic_search_request_builder.rs`](https://github.com/macro-inc/macro/blob/main/basic_search_request_builder.rs)** — Builds typed OpenSearch queries using the query builder crate

## Service-Level Demo Examples

For direct service interaction without the higher-level SDK, Macro provides examples that call individual services. These are useful for testing, debugging, or building custom integrations.

### Send Push Notifications

The notification service example ([`services/notification_service/examples/send_push_notification.rs`](https://github.com/macro-inc/macro/blob/main/services/notification_service/examples/send_push_notification.rs)) demonstrates authenticated push delivery:

```rust
// services/notification_service/examples/send_push_notification.rs
use notification_service_client::NotificationClient;
use notification_service_client::types::PushMessage;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let client = NotificationClient::new_from_env()?;

    let payload = PushMessage {
        title: "Hello from Macro!".into(),
        body: "Your task is ready".into(),
        user_id: "user-42".into(),
    };

    client.send_push(payload).await?;
    println!("Push notification sent");
    Ok(())
}

```

Contacts service examples include:
- **[`worker.rs`](https://github.com/macro-inc/macro/blob/main/worker.rs)** — Background worker pattern for processing contact sync jobs
- **[`generate_message.rs`](https://github.com/macro-inc/macro/blob/main/generate_message.rs)** — Formatted message payload generation for CRM workflows

### Static File Operations

The `static_file_service_client` crate includes examples for direct file storage operations:

- **[`put_file.rs`](https://github.com/macro-inc/macro/blob/main/put_file.rs)** — Uploads a file with automatic content-type detection
- **[`delete_file.rs`](https://github.com/macro-inc/macro/blob/main/delete_file.rs)** — Deletes a file by its storage key

## Agent Runtime Protocol Examples

For building custom agents, the `agent_runtime_protocol` crate provides low-level protocol examples:

- **[`websocket.rs`](https://github.com/macro-inc/macro/blob/main/websocket.rs)** — Opens and manages WebSocket connections to the agent runtime
- **[`mock_container.rs`](https://github.com/macro-inc/macro/blob/main/mock_container.rs)** — Mocks container environment for local agent testing
- **[`events.rs`](https://github.com/macro-inc/macro/blob/main/events.rs)** — Handles agent lifecycle event streams

## Complete File Reference for Macro Inc. Example Projects

| File Path | Language | What It Demonstrates |
|-----------|----------|----------------------|
| [`packages/sdk/examples/webhook-events.ts`](https://github.com/macro-inc/macro/blob/main/packages/sdk/examples/webhook-events.ts) | TypeScript | Full webhook registration with signature verification and event logging |
| [`packages/sdk/examples/doc-dump.ts`](https://github.com/macro-inc/macro/blob/main/packages/sdk/examples/doc-dump.ts) | TypeScript | Bulk document retrieval via SDK |
| [`packages/sdk/examples/channel-webhook.ts`](https://github.com/macro-inc/macro/blob/main/packages/sdk/examples/channel-webhook.ts) | TypeScript | Channel-specific webhook handler |
| [`packages/sdk/examples/channel-probe.ts`](https://github.com/macro-inc/macro/blob/main/packages/sdk/examples/channel-probe.ts) | TypeScript | Channel introspection and state queries |
| [`crates/documents/examples/documents_consumer.rs`](https://github.com/macro-inc/macro/blob/main/crates/documents/examples/documents_consumer.rs) | Rust | Live stream consumption from document service |
| [`crates/channels/examples/channels_consumer.rs`](https://github.com/macro-inc/macro/blob/main/crates/channels/examples/channels_consumer.rs) | Rust | Real-time message streaming from channels |
| [`crates/projects/examples/projects_consumer.rs`](https://github.com/macro-inc/macro/blob/main/crates/projects/examples/projects_consumer.rs) | Rust | Project activity event consumption |
| [`crates/opensearch_query_builder/examples/basic_search_request_builder.rs`](https://github.com/macro-inc/macro/blob/main/crates/opensearch_query_builder/examples/basic_search_request_builder.rs) | Rust | Type-safe OpenSearch query construction |
| [`crates/static_file_service_client/examples/put_file.rs`](https://github.com/macro-inc/macro/blob/main/crates/static_file_service_client/examples/put_file.rs) | Rust | File upload to static storage |
| [`crates/static_file_service_client/examples/delete_file.rs`](https://github.com/macro-inc/macro/blob/main/crates/static_file_service_client/examples/delete_file.rs) | Rust | File deletion from storage |
| [`services/notification_service/examples/send_push_notification.rs`](https://github.com/macro-inc/macro/blob/main/services/notification_service/examples/send_push_notification.rs) | Rust | Authenticated push notification delivery |
| [`services/contacts_service/examples/worker.rs`](https://github.com/macro-inc/macro/blob/main/services/contacts_service/examples/worker.rs) | Rust | Background job processing pattern |
| [`services/contacts_service/examples/generate_message.rs`](https://github.com/macro-inc/macro/blob/main/services/contacts_service/examples/generate_message.rs) | Rust | CRM message payload formatting |
| [`crates/agent_runtime_protocol/examples/websocket.rs`](https://github.com/macro-inc/macro/blob/main/crates/agent_runtime_protocol/examples/websocket.rs) | Rust | WebSocket client for agent runtime |
| [`crates/agent_runtime_protocol/examples/mock_container.rs`](https://github.com/macro-inc/macro/blob/main/crates/agent_runtime_protocol/examples/mock_container.rs) | Rust | Container mocking for local development |

## How to Run These Example Projects

All examples are **self-contained** and executable after setting up the Macro development environment. Per [`docs/RUNNING_LOCALLY.md`](https://github.com/macro-inc/macro/blob/main/docs/RUNNING_LOCALLY.md):

1. Clone `macro-inc/macro` and install dependencies (Rust toolchain, Bun, Docker)
2. Start the local service stack
3. Export `MACRO_BOT_TOKEN` for SDK examples or service environment variables for Rust examples
4. Run with `bun examples/<file>.ts` (TypeScript) or `cargo run --example <name>` (Rust)

## Summary

- **Macro Inc. example projects** span TypeScript SDK demos, Rust streaming consumers, service-level integrations, and agent protocol implementations
- **TypeScript SDK examples** in `packages/sdk/examples/` focus on webhook handling, document access, and channel operations
- **Rust crate examples** in `crates/*/examples/` demonstrate live stream consumption from documents, channels, and projects
- **Service demos** in `services/*/examples/` show push notifications, background workers, and file operations
- All examples are production-representative templates that can be adapted for live integrations

## Frequently Asked Questions

### Where are the official Macro Inc. example projects located?

The official examples are distributed throughout the `macro-inc/macro` repository. TypeScript SDK examples live in `packages/sdk/examples/`, Rust service client examples are in `crates/*/examples/`, and standalone service demos are in `services/*/examples/`. Each directory contains runnable files with embedded documentation.

### Do I need a running Macro instance to use these examples?

Yes. Most examples require a local or remote Macro environment with valid authentication. TypeScript examples need `MACRO_BOT_TOKEN` exported, while Rust examples typically use `new_from_env()` to load connection details from environment variables. See [`docs/RUNNING_LOCALLY.md`](https://github.com/macro-inc/macro/blob/main/docs/RUNNING_LOCALLY.md) for full setup instructions.

### Can I use these examples as templates for production code?

Absolutely. According to the source code, these examples are designed as **self-contained, production-representative templates**. The webhook handling patterns, streaming consumer implementations, and service call structures follow the same patterns used internally at Macro Inc.