Macro Example Usage Scenarios and Demos: A Complete Guide

The macro-inc/macro repository ships with ready-to-run TypeScript SDK examples, interactive SolidJS UI demonstrations, and Docker-based local development environments to help developers explore the platform's capabilities.

The macro-inc/macro project provides comprehensive example usage scenarios and demos that illustrate core platform concepts and SDK integration patterns. These resources range from standalone scripts that interact with the API to embedded UI components within the onboarding flow. Developers can use these concrete implementations to understand real-time webhook handling, document manipulation, and frontend component architecture.

TypeScript SDK Examples

The packages/sdk/examples/ directory contains executable scripts demonstrating how to build bots and automate workflows using the Macro SDK.

Real-Time Webhook Event Handling

The packages/sdk/examples/webhook-events.ts file demonstrates how to register a webhook and listen to every Macro event. This script initializes a bot client, registers a webhook with a custom namespace, and sets up an event dispatcher that verifies webhook signatures.

// packages/sdk/examples/webhook-events.ts
import { Macro } from '../src/macro';

const [url, actingUser] = process.argv.slice(2);
const botToken = process.env.MACRO_BOT_TOKEN;
if (!url || !actingUser || !botToken) {
  console.error(
    'usage: MACRO_BOT_TOKEN=… bun examples/webhook-events.ts <public-url> <acting-user-id>',
  );
  process.exit(1);
}

// Initialise a Macro client as a bot
const macro = new Macro({
  env: (process.env.MACRO_ENV ?? 'dev') as any,
  auth: { type: 'bot', token: botToken },
}).requestedAs(actingUser);

// All supported events are enumerated in ALL_EVENTS
const ALL_EVENTS = [
  'channel.created',
  'channel.deleted',
  'channel.message_posted',
  // … (see file for full list)
] as const;

// Register the webhook
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;

// Set up an event dispatcher that verifies the signature
const events = new Macro({
  env: macro.env,
  auth: macro.auth,
  webhookSecret: secret,
}).events;

for (const name of ALL_EVENTS) {
  events.on(name, (e) => console.log(name, e.metadata));
}
const receiver = events.webhook();   // <- returns an async request handler

Run this demo using Bun:

MACRO_BOT_TOKEN=mbot_… bun examples/webhook-events.ts https://my‑public‑url.example.com <user‑id>

The script outputs each incoming event name and its metadata, providing a concise way to explore the full event payload surface.

Document and Channel Operations

Additional SDK examples include packages/sdk/examples/doc-dump.ts, which retrieves a document's JSON representation, and packages/sdk/examples/channel-probe.ts, which demonstrates fetching channel participants and recent messages. Both files instantiate the Macro class with bot authentication and showcase different API surface areas.

Interactive SolidJS UI Demos

The web application includes demo components that render UI primitives used throughout the onboarding flow. These live in apps/web/src/lib/core/internal/ and demonstrate interactive patterns such as avatars, SVG noise grids, resize panels, and markdown mentions.

Onboarding Lesson Demos

The onboarding system embeds demo components directly into step-by-step walkthroughs. For example, apps/web/src/features/onboarding/lessons/markdown-mentions.tsx contains the MarkdownMentionsDemo component:

// apps/web/src/features/onboarding/lessons/markdown-mentions.tsx
function MarkdownMentionsDemo(props: LessonContentProps) {
  // The demo renders a markdown editor with live @‑mention handling.
  // It is wired via the Macro “entity‑mention” service.
  const { editor, setEditor } = useMarkdownEditor();

  return (
    <div class="demo-container">
      <MarkdownEditor value={editor} onChange={setEditor} />
      <MentionSuggestions />
    </div>
  );
}

The lesson exports a definition object that registers this component:

export const MarkdownMentionsLesson = {
  title: 'Markdown Mentions',
  definition: {
    // …
    demo: MarkdownMentionsDemo,
  },
};

You can view this demo in the web UI by opening the onboarding modal (press ? in the app) and selecting the "Markdown Mentions" lesson. Other internal demos like UserIconDemo.tsx showcase avatar primitives used across the application interface.

Local Development Environment

For developers wanting to explore the full stack, the repository includes Docker Compose configurations to spin up all required services.

Create a complete local environment with:

# From the repo root

docker compose -f docker/docker-compose.yml up -d

This launches PostgreSQL, Redis, OpenSearch, and all microservices. Then initialize the database and run tests:

just setup_macrodb  # creates the main DB schema

just test           # runs the Rust test suite

Finally, start the web client to access the UI demos:

cd apps/web
pnpm install
pnpm dev

This local instance provides access to all example usage scenarios and demos in a self-contained environment.

Summary

• The TypeScript SDK provides three main example scripts in packages/sdk/examples/ for webhook handling, document inspection, and channel probing.
• SolidJS UI demos are embedded throughout the web application, particularly in onboarding lessons under apps/web/src/features/onboarding/lessons/.
• The Docker Compose setup in docker/docker-compose.yml enables full-stack local development with all backend services.
• All demos instantiate the Macro class using bot authentication patterns and demonstrate production-ready integration techniques.

Frequently Asked Questions

How do I run the webhook events demo in the Macro repository?

Execute the script using Bun with the required environment variables. Run MACRO_BOT_TOKEN=mbot_… bun examples/webhook-events.ts <public-url> <user-id> from the packages/sdk directory. The script registers a webhook for all supported events and prints incoming payloads to the console.

Where can I find UI demo components in the Macro codebase?

UI demos reside in apps/web/src/lib/core/internal/ and apps/web/src/features/onboarding/lessons/. Files like UserIconDemo.tsx and markdown-mentions.tsx contain interactive components used in the onboarding flow that you can view by pressing ? in the web application.

Does the Macro project include a local development environment?

Yes. The repository includes docker/docker-compose.yml and docker/docker-compose-databases.yml to launch PostgreSQL, Redis, OpenSearch, and all microservices. Use just setup_macrodb to initialize the schema and pnpm dev in apps/web to start the frontend with all demos enabled.

What programming languages are used in the Macro examples?

The SDK examples use TypeScript and run on the Bun runtime. The web demos use SolidJS (TypeScript/TSX) for UI components. The backend services referenced in the Docker Compose setup are primarily Rust based, as evidenced by the just test command running the Rust test suite.

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