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

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 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.

// 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 — Dumps all documents accessible to the bot for quick inspection
• channel-webhook.ts — Minimal webhook that filters only for channel.* events
• 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 example in crates/channels/examples/ shows how to consume a live stream of messages from a specific channel:

// 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 — Streams document creation, update, and deletion events
• projects_consumer.rs — Consumes project-wide activity and lifecycle events
• 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) demonstrates authenticated push delivery:

// 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 — Background worker pattern for processing contact sync jobs
• 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 — Uploads a file with automatic content-type detection
• 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 — Opens and manages WebSocket connections to the agent runtime
• mock_container.rs — Mocks container environment for local agent testing
• 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	TypeScript	Full webhook registration with signature verification and event logging
packages/sdk/examples/doc-dump.ts	TypeScript	Bulk document retrieval via SDK
packages/sdk/examples/channel-webhook.ts	TypeScript	Channel-specific webhook handler
packages/sdk/examples/channel-probe.ts	TypeScript	Channel introspection and state queries
crates/documents/examples/documents_consumer.rs	Rust	Live stream consumption from document service
crates/channels/examples/channels_consumer.rs	Rust	Real-time message streaming from channels
crates/projects/examples/projects_consumer.rs	Rust	Project activity event consumption
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	Rust	File upload to static storage
crates/static_file_service_client/examples/delete_file.rs	Rust	File deletion from storage
services/notification_service/examples/send_push_notification.rs	Rust	Authenticated push notification delivery
services/contacts_service/examples/worker.rs	Rust	Background job processing pattern
services/contacts_service/examples/generate_message.rs	Rust	CRM message payload formatting
crates/agent_runtime_protocol/examples/websocket.rs	Rust	WebSocket client for agent runtime
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:

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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}