Skip to content

armgit / macro

Public Imported from GitHub
0

Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.

5.7 KB
Raw Blame
import type {
  PatchWebhookRequest,
  ValidateWebhookResponse,
  WebhookFilter,
  Webhook as WebhookRecord,
  WebhookScope,
} from '../../../generated/storage/types.gen';
import { unwrap } from '../../utils';
import type { MacroClient } from '../../utils/client';
import { MacroEntity } from '../entity';
import { User } from '../users/user';

/**
 * A webhook registration: an HTTPS endpoint Macro delivers signed entity
 * events to.
 *
 * A free-to-construct `(client, id)` handle like any other entity: the detail
 * record loads lazily from the webhook GET endpoint on first field access and
 * is dropped after any mutation. {@link WebhooksNamespace.list} enumerates the
 * caller's webhooks across their personal and team workspaces.
 *
 * The signing secret is only ever returned once, from {@link create}; it's
 * exposed there as {@link Webhook.signingSecret}. Save it — patches, gets,
 * and `byId` handles never carry it again — and pass it to
 * `MacroOpts.webhookSecret` so `macro.events.webhook()` can verify
 * deliveries. Live SSE via `macro.events.listen()` does not use a
 * persisted webhook or signing secret.
 */
export class Webhook extends MacroEntity<WebhookRecord> {
  /**
   * The signing secret used to verify deliveries, present only on the handle
   * returned by {@link create}. `undefined` for `byId` and listed handles.
   */
  readonly signingSecret?: string;

  private constructor(
    client: MacroClient,
    id: string,
    seed?: WebhookRecord,
    signingSecret?: string,
  ) {
    super(client, id, seed);
    this.signingSecret = signingSecret;
  }

  protected async fetch(): Promise<WebhookRecord> {
    return unwrap(
      await this.client.storage.getWebhook({
        path: { webhook_id: this.id },
      }),
    );
  }

  /** Register a webhook. */
  static async create(
    client: MacroClient,
    opts: {
      url: string;
      namespace: string;
      name: string;
      filters: WebhookFilter[];
      scope?: WebhookScope;
      headers?: Record<string, string>;
    },
  ): Promise<Webhook> {
    const record = unwrap(
      await client.storage.createWebhook({
        body: {
          endpoint_url: opts.url,
          namespace: opts.namespace,
          name: opts.name,
          filters: opts.filters,
          scope: opts.scope ?? 'user',
          ...(opts.headers !== undefined ? { headers: opts.headers } : {}),
        },
      }),
    );
    return new Webhook(client, record.id, record, record.signing_secret);
  }

  /** A handle to a webhook by id. Details load on first access. */
  static byId(client: MacroClient, id: string): Webhook {
    return new Webhook(client, id);
  }

  /** Wrap an already-loaded record. */
  static fromRecord(client: MacroClient, record: WebhookRecord): Webhook {
    return new Webhook(client, record.id, record);
  }

  /** The webhook's display name. */
  readonly name = this.field('name');

  /**
   * The caller-chosen namespace, unique among the owning workspace's webhooks.
   * Fixed at creation time; it cannot be patched.
   */
  readonly namespace = this.field('namespace');

  /** The HTTPS endpoint URL deliveries are sent to. */
  readonly endpointUrl = this.field('endpoint_url');

  /** The webhook's lifecycle status. */
  readonly status = this.field('status');

  /** Whether the current endpoint configuration has passed validation. */
  readonly isValid = this.field('is_valid');

  /** The event/entity-id filters that gate deliveries. */
  readonly filters = this.field('filters');

  /** When the webhook was created. */
  readonly createdAt = this.field('created_at');

  /** The owning workspace id: the creator's user id for a personal webhook, or a team id for a team webhook. */
  readonly workspaceId = this.field('workspace_id');

  /** The user who registered this webhook. */
  readonly createdBy = this.mappedField('created_by_user_id', (id) =>
    User.byId(this.client, id),
  );

  /**
   * Whether this webhook is owned by the caller personally (`user`) or by
   * their team (`team`). Derived from ownership: a personal webhook's owning
   * workspace is the creator's own user id, whereas a team webhook's workspace
   * is a distinct team id.
   */
  async scope(): Promise<WebhookScope> {
    const record = await this.detail.get();
    return record.workspace_id === record.created_by_user_id ? 'user' : 'team';
  }

  /** Update the webhook. */
  public async update(body: PatchWebhookRequest): Promise<void> {
    await this.mutate((client) =>
      client.storage.patchWebhook({
        path: { webhook_id: this.id },
        body,
      }),
    );
  }

  /** Rename the webhook. */
  async rename(name: string): Promise<void> {
    await this.update({ name });
  }

  /** Point the webhook at a new HTTPS endpoint URL. */
  async setUrl(url: string): Promise<void> {
    await this.update({ endpoint_url: url });
  }

  /** Replace the webhook's delivery filters (must be non-empty). */
  async setFilters(filters: WebhookFilter[]): Promise<void> {
    await this.update({ filters });
  }

  /** Pause deliveries. */
  async pause(): Promise<void> {
    await this.update({ status: 'paused' });
  }

  /** Resume deliveries. */
  async resume(): Promise<void> {
    await this.update({ status: 'active' });
  }

  /** Delete the webhook. */
  async delete(): Promise<void> {
    await this.mutate((client) =>
      client.storage.deleteWebhook({
        path: { webhook_id: this.id },
      }),
    );
  }

  /**
   * Send a signed validation test delivery to the endpoint and report whether
   * it was accepted. Drops the cached detail so a subsequent {@link isValid}
   * read reflects the new validation state.
   */
  async validate(): Promise<ValidateWebhookResponse> {
    return this.mutate((client) =>
      client.storage.validateWebhook({
        path: { webhook_id: this.id },
      }),
    );
  }
}