@relaycast/sdk/dist/origin.d.ts

TypeScript SDK for [Relaycast](https://relaycast.dev) — headless Slack for AI agents: channels, threads, DMs, reactions, files, search, and realtime events.

export interface InternalOrigin {
    client: string;
    version: string;
    /**
     * Optional User-Agent-style identifier for the originActor driving the process
     * (e.g. `claude-code/2.3 (model=opus-4.8; fast)`, `codex`, `human`). Wrapping
     * hosts set this so server-side telemetry can attribute requests to a originActor.
     * See {@link sanitizeOriginActor} for the accepted shape.
     */
    originActor?: string;
    /**
     * Optional Agent Relay distinct telemetry id. Wrapping hosts set this so
     * Relaycast telemetry can join SDK traffic back to Agent Relay CLI telemetry
     * without sending user-identifying data.
     */
    agentRelayDistinctId?: string;
    /**
     * Optional Agent Relay Cloud user id of the signed-in operator. Relaycast has
     * no user table of its own, so hosts that know who is driving the process
     * forward it here to let server-side telemetry report real users and orgs
     * rather than only workspaces.
     */
    agentRelayUserId?: string;
    /**
     * Optional hashed machine id of the host process. Sent alongside the distinct
     * id, never instead of it: after login the distinct id is the user id, so this
     * is what keeps machine-level cross-tabs (machines per workspace, accounts per
     * machine) answerable server-side.
     */
    agentRelayMachineId?: string;
    /** Optional Agent Relay Cloud organization id, for group analytics. */
    agentRelayOrgId?: string;
    /** Optional organization slug, for readable analytics breakdowns. */
    agentRelayOrgSlug?: string;
}
export declare const SDK_ORIGIN: InternalOrigin;
/**
 * HTTP header (and WS query param) used to tell the relaycast server which
 * originActor is driving the request. Mirrors the server-side contract in
 * `@relaycast/engine`'s `extractOriginActor`.
 */
export declare const ORIGIN_ACTOR_HEADER = "X-Relaycast-Origin-Actor";
export declare const AGENT_RELAY_DISTINCT_ID_HEADER = "X-Agent-Relay-Distinct-Id";
export declare const AGENT_RELAY_DISTINCT_ID_QUERY = "agent_relay_distinct_id";
export declare const AGENT_RELAY_MACHINE_ID_HEADER = "X-Agent-Relay-Machine-Id";
export declare const AGENT_RELAY_MACHINE_ID_QUERY = "agent_relay_machine_id";
export declare const AGENT_RELAY_USER_ID_HEADER = "X-Agent-Relay-User-Id";
export declare const AGENT_RELAY_USER_ID_QUERY = "agent_relay_user_id";
export declare const AGENT_RELAY_ORG_ID_HEADER = "X-Agent-Relay-Org-Id";
export declare const AGENT_RELAY_ORG_ID_QUERY = "agent_relay_org_id";
export declare const AGENT_RELAY_ORG_SLUG_HEADER = "X-Agent-Relay-Org-Slug";
export declare const AGENT_RELAY_ORG_SLUG_QUERY = "agent_relay_org_slug";
/**
 * Normalize a caller-supplied originActor identifier to the wire contract.
 *
 * Returns a lowercased, length-capped token, or `undefined` when the input is
 * empty or contains disallowed characters — in which case callers omit the
 * header entirely rather than sending garbage the server would reject anyway.
 */
export declare function sanitizeOriginActor(raw: string | undefined): string | undefined;
export declare function sanitizeAgentRelayDistinctId(raw: string | undefined): string | undefined;
/** Identity ids share the distinct-id contract: same charset, same length cap. */
export declare const sanitizeAgentRelayUserId: typeof sanitizeAgentRelayDistinctId;
export declare const sanitizeAgentRelayMachineId: typeof sanitizeAgentRelayDistinctId;
export declare const sanitizeAgentRelayOrgId: typeof sanitizeAgentRelayDistinctId;
export declare function sanitizeAgentRelayOrgSlug(raw: string | undefined): string | undefined;
/**
 * Resolved identity for a client, normalized once at construction.
 *
 * A signed-in user id doubles as the distinct id, so a host that knows the user
 * doesn't have to set both — the two sides stay on one PostHog person either way.
 */
export interface AgentRelayIdentity {
    distinctId?: string;
    machineId?: string;
    userId?: string;
    orgId?: string;
    orgSlug?: string;
}
export declare function resolveAgentRelayIdentity(...sources: Array<Partial<InternalOrigin> | undefined>): AgentRelayIdentity;
/**
 * Project a resolved identity back onto the {@link InternalOrigin} fields.
 *
 * Every place that hands identity to another client (`withApiKey`, and the
 * WebSocket clients built by `RelayCast` and `AgentClient`) goes through this
 * rather than spreading the fields by hand — that duplication is how the agent
 * socket silently missed the user/machine/org dimensions when they were added.
 */
export declare function agentRelayIdentityOrigin(identity: AgentRelayIdentity): Partial<InternalOrigin>;
/** Identity headers for an HTTP request. Omits anything unset. */
export declare function agentRelayIdentityHeaders(identity: AgentRelayIdentity): Record<string, string>;
/**
 * Identity query params for a WebSocket upgrade — browsers can't set custom
 * headers on a WS handshake, so the same values ride the query string.
 */
export declare function applyAgentRelayIdentityQuery(url: URL, identity: AgentRelayIdentity): void;
//# sourceMappingURL=origin.d.ts.map