Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.
TypeScript agentaiai-agentsall-in-onecrmcrm-systememaillinearmcpmessagingnotesnotionofficerustslackslack-alternativestartupstartup-toolstypescriptworkspace
export type Env = 'dev' | 'prod' | 'local';
/** The backend services the SDK talks to. Note `search` and `properties` are
* served on the storage host, so they point there. */
export type ServiceName =
| 'agent-harness'
| 'storage'
| 'auth'
| 'email'
| 'calendar'
| 'cognition'
| 'notification'
| 'properties'
| 'search'
| 'scheduled-action'
| 'static-files'
| 'connection'
| 'contacts'
| 'unfurl';
export const WEB_APP_URLS: Record<Env, string> = {
dev: 'https://dev.macro.com',
prod: 'https://macro.com',
local: 'http://localhost:3000',
};
export const HOSTS: Record<Env, Record<ServiceName, string>> = {
dev: {
'agent-harness': 'https://dev-gateway.macro.com/agent-harness',
storage: 'https://dev-gateway.macro.com/dss',
auth: 'https://dev-gateway.macro.com/auth',
email: 'https://dev-gateway.macro.com/email',
calendar: 'https://dev-gateway.macro.com/calendar',
cognition: 'https://dev-gateway.macro.com/cognition',
notification: 'https://dev-gateway.macro.com/notification',
properties: 'https://dev-gateway.macro.com/dss',
search: 'https://dev-gateway.macro.com/dss',
'scheduled-action': 'https://dev-gateway.macro.com/scheduled-action',
'static-files': 'https://static-file-service-dev.macro.com',
connection: 'https://dev-gateway.macro.com/connection-gateway',
contacts: 'https://dev-gateway.macro.com/contacts',
unfurl: 'https://dev-gateway.macro.com/unfurl',
},
prod: {
'agent-harness': 'https://gateway.macro.com/agent-harness',
storage: 'https://gateway.macro.com/dss',
auth: 'https://gateway.macro.com/auth',
email: 'https://gateway.macro.com/email',
calendar: 'https://gateway.macro.com/calendar',
cognition: 'https://gateway.macro.com/cognition',
notification: 'https://gateway.macro.com/notification',
properties: 'https://gateway.macro.com/dss',
search: 'https://gateway.macro.com/dss',
'scheduled-action': 'https://gateway.macro.com/scheduled-action',
'static-files': 'https://static-file-service.macro.com',
connection: 'https://gateway.macro.com/connection-gateway',
contacts: 'https://gateway.macro.com/contacts',
unfurl: 'https://gateway.macro.com/unfurl',
},
local: {
'agent-harness': 'http://localhost:8101',
storage: 'http://localhost:8086',
auth: 'http://localhost:8080',
email: 'http://localhost:8087',
// calendar_service serves its routes under `/calendar` as well as at the
// root; the `/calendar` segment keeps local paths identical to the
// gateway's. Mirrors apps/web servers.ts.
calendar: 'http://localhost:8088/calendar',
cognition: 'http://localhost:8101/cognition',
notification: 'http://localhost:8089',
properties: 'http://localhost:8086',
search: 'http://localhost:8086',
'scheduled-action': 'http://localhost:8101/scheduled-action',
'static-files': 'http://localhost:8100',
connection: 'http://localhost:8082',
contacts: 'http://localhost:8083',
unfurl: 'http://localhost:8095',
},
};
/** A credential string, or a (possibly async) function that returns one. */
export type TokenSource = string | (() => string | Promise<string>);
/** Access scope for bot-authenticated requests. `user` acts with the
* requested-as user's access (requires `requestedAs`); `team` acts with the
* bot's owning team's access (team-owned bots only). */
export type BotScope = 'user' | 'team';
/**
* How the SDK authenticates with Macro.
*
* A user has exactly one of two credential fields.
*
* - `token`: a bearer token, or a `mak_` API key. The SDK picks the header
* from the prefix at send time.
* - `apiKey`: a Settings → API Keys key, always sent as
* `x-macro-user-api-key`. Not prefix-checked, so keys that predate the
* `mak_` prefix work here.
*
* A bot uses an `mbot_` token as `x-macro-bot-token` plus
* `x-macro-bot-scope`, defaulting to `user` when `requestedAs` is set and
* `team` otherwise.
*/
export type MacroAuth =
| { type: 'user'; token: TokenSource; apiKey?: never }
| { type: 'user'; apiKey: string; token?: never }
| { type: 'bot'; token: TokenSource; scope?: BotScope };
/** Options passed to `new Macro(opts)` and stored on `MacroClient`. */
export interface MacroOpts {
/** Optional generated API operation events; excludes arguments, URLs and response data. */
onRequest?: (event: import('./utils/activity').RequestActivity) => void;
/** How to authenticate. Takes precedence over `token`. Falls back to
* `MACRO_API_KEY` (a user API key or bearer token) or `MACRO_BOT_TOKEN`
* (bot). */
auth?: MacroAuth;
/** Shorthand for `auth: { type: 'user', token }`. Accepts a Settings API
* key (`mak_…`) or a bearer token. */
token?: TokenSource;
/** Which Macro environment to talk to. Falls back to the MACRO_ENV env
* var, then `'prod'`. */
env?: Env;
/** Override individual service hosts (e.g. point one at localhost). */
hosts?: Partial<Record<ServiceName, string>>;
/** Override the web app base URL (e.g. for local frontend dev). Also reads MACRO_WEB_URL. */
webAppUrl?: string;
/**
* Signing secret for verifying incoming persisted-webhook deliveries.
* Required only for `macro.events.webhook()` / `macro.events.handle()`.
* SSE via `macro.events.listen()` uses the API token and does not need
* this. Falls back to MACRO_WEBHOOK_SECRET.
*/
webhookSecret?: string;
wsVerify?: string;
/** User id the bot acts for, sent as `x-macro-bot-for-macro-user-id` on
* every request. Bot auth only. Set via `macro.requestedAs(user)` rather
* than directly. */
requestedAs?: string;
}