hobots 1.3.5 → 1.5.0

package/dist/index.d.cts

@@ -1,8 +1,121 @@
-import { Severity, EventPayload, Breadcrumb, EventUser, TransactionPayload, CheckInPayload, HeartbeatPayload, SpanData, CheckInStatus } from './protocol.cjs';
+import { Breadcrumb, EventUser, Severity, EventPayload, TransactionPayload, CheckInPayload, HeartbeatPayload, SpanStatus, SpanData, CheckInStatus } from './protocol.cjs';
 export { Envelope, EnvelopeItem, ExceptionData, StackFrame } from './protocol.cjs';
 import { ManagerPollRequest, ManagerPollResponse, ManagerRunUpdateRequest } from './manager/protocol.cjs';
 export { ManagerAgentInfo, ManagerRunDescriptor, ManagerRunError, ManagerRunStatus, ManagerRunUpdateResponse, ManagerRunUpdateStatus, RunLogEntry, RunLogLevel } from './manager/protocol.cjs';
 
+/** API oficial da Hobots — o SDK sempre fala com ela em produção. */
+declare const DEFAULT_BASE_URL = "https://api2.hobots.app";
+interface ResolvedConfig {
+    /** Client Secret do projeto (enviado como Authorization: Bearer, nunca na URL) */
+    key: string;
+    baseUrl: string;
+    /** Ingestão do Monitor: <baseUrl>/v1/ingest */
+    ingestEndpoint: string;
+    /** API do Manager: <baseUrl>/v1/manager */
+    managerBaseUrl: string;
+}
+interface ConfigInput {
+    clientSecret: string;
+}
+/** Resolve o clientSecret nos endpoints do Monitor e do Manager. */
+declare function resolveConfig(options: ConfigInput, prefix?: string): ResolvedConfig;
+
+type BreadcrumbInput = Omit<Breadcrumb, 'timestamp'> & {
+    timestamp?: string;
+};
+/** Estado contextual anexado aos eventos: tags, usuário, contexts, extras e breadcrumbs. */
+declare class Scope {
+    tags: Record<string, string>;
+    user?: EventUser;
+    contexts: Record<string, Record<string, unknown>>;
+    extra: Record<string, unknown>;
+    level?: Severity;
+    fingerprint?: string[];
+    breadcrumbs: Breadcrumb[];
+    setTag(key: string, value: string): this;
+    setTags(tags: Record<string, string>): this;
+    setUser(user: EventUser | null): this;
+    setContext(name: string, context: Record<string, unknown> | null): this;
+    setExtra(key: string, value: unknown): this;
+    setExtras(extras: Record<string, unknown>): this;
+    setLevel(level: Severity): this;
+    setFingerprint(fingerprint: string[]): this;
+    addBreadcrumb(crumb: BreadcrumbInput, maxBreadcrumbs: number): this;
+    clearBreadcrumbs(): this;
+    clone(): Scope;
+}
+
+interface Logger {
+    debug: (...args: unknown[]) => void;
+    warn: (...args: unknown[]) => void;
+    error: (...args: unknown[]) => void;
+}
+
+declare class Client {
+    readonly options: InitOptions;
+    readonly config: ResolvedConfig;
+    readonly logger: Logger;
+    private readonly transport;
+    constructor(options: InitOptions);
+    captureException(error: unknown, hint: CaptureHint | undefined, scope: Scope): string;
+    captureMessage(message: string, level: Severity, hint: CaptureHint | undefined, scope: Scope): string;
+    captureEvent(event: EventPayload, hint: CaptureHint | undefined, scope: Scope): string;
+    private prepareEvent;
+    sendTransaction(payload: TransactionPayload): void;
+    sendCheckIn(payload: CheckInPayload): void;
+    sendHeartbeat(payload: HeartbeatPayload): void;
+    flush(timeoutMs?: number): Promise<boolean>;
+    close(timeoutMs?: number): Promise<boolean>;
+}
+
+declare class Span {
+    private readonly transaction;
+    readonly parentSpanId: string;
+    readonly op?: string | undefined;
+    readonly description?: string | undefined;
+    readonly spanId: string;
+    readonly startTimestamp: string;
+    status: SpanStatus;
+    endTimestamp?: string;
+    data?: Record<string, unknown>;
+    constructor(transaction: Transaction, parentSpanId: string, op?: string | undefined, description?: string | undefined);
+    setStatus(status: SpanStatus): this;
+    setData(key: string, value: unknown): this;
+    /** Span aninhado (filho deste span). */
+    startChild(op?: string, description?: string): Span;
+    finish(): void;
+    toJSON(): SpanData;
+}
+/**
+ * Uma unidade de trabalho nomeada (ex.: uma execução de rotina, uma sincronização).
+ * Spans filhos medem as etapas internas (chamadas HTTP, queries, etc.).
+ */
+declare class Transaction {
+    private readonly client;
+    name: string;
+    readonly op?: string | undefined;
+    private readonly sampled;
+    /** Correlaciona a uma execução do Manager — preenchido automaticamente em ctx.tx */
+    private readonly runId?;
+    readonly eventId: string;
+    readonly spanId: string;
+    readonly startTimestamp: string;
+    status: string;
+    private readonly spans;
+    private readonly tags;
+    private finished;
+    constructor(client: Client | undefined, name: string, op?: string | undefined, sampled?: boolean, 
+    /** Correlaciona a uma execução do Manager — preenchido automaticamente em ctx.tx */
+    runId?: string | undefined);
+    createSpan(parentSpanId: string, op?: string, description?: string): Span;
+    /** Span direto da transaction. */
+    startChild(op?: string, description?: string): Span;
+    setTag(key: string, value: string): this;
+    setStatus(status: string): this;
+    setName(name: string): this;
+    finish(): void;
+}
+
 /** Opções do Manager dentro de `init({ manager: ... })`. Credencial (clientSecret), identidade (instanceId) e debug vêm do init. */
 interface ManagerOptions {
     /** Intervalo entre polls sem trabalho. Default: 5_000 (mínimo 1_000) */
@@ -38,6 +151,8 @@ interface ManagerAgentOptions extends ManagerOptions {
     instanceId: string;
     /** Loga atividade do SDK no console */
     debug?: boolean;
+    /** Client do Monitor compartilhado — usado para enviar a transaction de performance de cada run (ctx.tx) */
+    client?: Client;
 }
 interface RunLogger {
     debug(message: string): void;
@@ -50,6 +165,12 @@ interface RunContext {
     task: string;
     /** Log bufferizado — enviado ao servidor em PATCHes incrementais com throttle */
     log: RunLogger;
+    /**
+     * Transaction de performance desta execução — já correlacionada à run e finalizada
+     * automaticamente ao fim do handler. Use `ctx.tx.startChild(op, description)` pra medir
+     * as etapas (steps) da task; elas aparecem como waterfall na aba de performance da execução.
+     */
+    tx: Transaction;
     /** Dispara em cancelamento (run cancelada no app), timeout ou shutdown — cancelamento cooperativo */
     signal: AbortSignal;
     /**
@@ -112,115 +233,6 @@ interface CaptureHint {
     fingerprint?: string[];
 }
 
-/** API oficial da Hobots — o SDK sempre fala com ela em produção. */
-declare const DEFAULT_BASE_URL = "https://api2.hobots.app";
-interface ResolvedConfig {
-    /** Client Secret do projeto (enviado como Authorization: Bearer, nunca na URL) */
-    key: string;
-    baseUrl: string;
-    /** Ingestão do Monitor: <baseUrl>/v1/ingest */
-    ingestEndpoint: string;
-    /** API do Manager: <baseUrl>/v1/manager */
-    managerBaseUrl: string;
-}
-interface ConfigInput {
-    clientSecret: string;
-}
-/** Resolve o clientSecret nos endpoints do Monitor e do Manager. */
-declare function resolveConfig(options: ConfigInput, prefix?: string): ResolvedConfig;
-
-type BreadcrumbInput = Omit<Breadcrumb, 'timestamp'> & {
-    timestamp?: string;
-};
-/** Estado contextual anexado aos eventos: tags, usuário, contexts, extras e breadcrumbs. */
-declare class Scope {
-    tags: Record<string, string>;
-    user?: EventUser;
-    contexts: Record<string, Record<string, unknown>>;
-    extra: Record<string, unknown>;
-    level?: Severity;
-    fingerprint?: string[];
-    breadcrumbs: Breadcrumb[];
-    setTag(key: string, value: string): this;
-    setTags(tags: Record<string, string>): this;
-    setUser(user: EventUser | null): this;
-    setContext(name: string, context: Record<string, unknown> | null): this;
-    setExtra(key: string, value: unknown): this;
-    setExtras(extras: Record<string, unknown>): this;
-    setLevel(level: Severity): this;
-    setFingerprint(fingerprint: string[]): this;
-    addBreadcrumb(crumb: BreadcrumbInput, maxBreadcrumbs: number): this;
-    clearBreadcrumbs(): this;
-    clone(): Scope;
-}
-
-interface Logger {
-    debug: (...args: unknown[]) => void;
-    warn: (...args: unknown[]) => void;
-    error: (...args: unknown[]) => void;
-}
-
-declare class Client {
-    readonly options: InitOptions;
-    readonly config: ResolvedConfig;
-    readonly logger: Logger;
-    private readonly transport;
-    constructor(options: InitOptions);
-    captureException(error: unknown, hint: CaptureHint | undefined, scope: Scope): string;
-    captureMessage(message: string, level: Severity, hint: CaptureHint | undefined, scope: Scope): string;
-    captureEvent(event: EventPayload, hint: CaptureHint | undefined, scope: Scope): string;
-    private prepareEvent;
-    sendTransaction(payload: TransactionPayload): void;
-    sendCheckIn(payload: CheckInPayload): void;
-    sendHeartbeat(payload: HeartbeatPayload): void;
-    flush(timeoutMs?: number): Promise<boolean>;
-    close(timeoutMs?: number): Promise<boolean>;
-}
-
-declare class Span {
-    private readonly transaction;
-    readonly parentSpanId: string;
-    readonly op?: string | undefined;
-    readonly description?: string | undefined;
-    readonly spanId: string;
-    readonly startTimestamp: string;
-    status: string;
-    endTimestamp?: string;
-    data?: Record<string, unknown>;
-    constructor(transaction: Transaction, parentSpanId: string, op?: string | undefined, description?: string | undefined);
-    setStatus(status: string): this;
-    setData(key: string, value: unknown): this;
-    /** Span aninhado (filho deste span). */
-    startChild(op?: string, description?: string): Span;
-    finish(): void;
-    toJSON(): SpanData;
-}
-/**
- * Uma unidade de trabalho nomeada (ex.: uma execução de rotina, uma sincronização).
- * Spans filhos medem as etapas internas (chamadas HTTP, queries, etc.).
- */
-declare class Transaction {
-    private readonly client;
-    name: string;
-    readonly op?: string | undefined;
-    private readonly sampled;
-    readonly eventId: string;
-    readonly spanId: string;
-    readonly startTimestamp: string;
-    status: string;
-    private readonly spans;
-    private readonly tags;
-    private finished;
-    constructor(client: Client | undefined, name: string, op?: string | undefined, sampled?: boolean);
-    createSpan(parentSpanId: string, op?: string, description?: string): Span;
-    /** Span direto da transaction. */
-    startChild(op?: string, description?: string): Span;
-    setTag(key: string, value: string): this;
-    setStatus(status: string): this;
-    setName(name: string): this;
-    finish(): void;
-}
-
 interface CheckInOptions {
     monitorSlug: string;
     status: CheckInStatus;
@@ -284,6 +296,7 @@ declare class ManagerAgent {
     private readonly registry;
     readonly logger: Logger;
     private readonly api;
+    private readonly client;
     private readonly pollIntervalMs;
     private readonly concurrency;
     private readonly instanceId;

package/dist/index.d.ts

@@ -1,8 +1,121 @@
-import { Severity, EventPayload, Breadcrumb, EventUser, TransactionPayload, CheckInPayload, HeartbeatPayload, SpanData, CheckInStatus } from './protocol.js';
+import { Breadcrumb, EventUser, Severity, EventPayload, TransactionPayload, CheckInPayload, HeartbeatPayload, SpanStatus, SpanData, CheckInStatus } from './protocol.js';
 export { Envelope, EnvelopeItem, ExceptionData, StackFrame } from './protocol.js';
 import { ManagerPollRequest, ManagerPollResponse, ManagerRunUpdateRequest } from './manager/protocol.js';
 export { ManagerAgentInfo, ManagerRunDescriptor, ManagerRunError, ManagerRunStatus, ManagerRunUpdateResponse, ManagerRunUpdateStatus, RunLogEntry, RunLogLevel } from './manager/protocol.js';
 
+/** API oficial da Hobots — o SDK sempre fala com ela em produção. */
+declare const DEFAULT_BASE_URL = "https://api2.hobots.app";
+interface ResolvedConfig {
+    /** Client Secret do projeto (enviado como Authorization: Bearer, nunca na URL) */
+    key: string;
+    baseUrl: string;
+    /** Ingestão do Monitor: <baseUrl>/v1/ingest */
+    ingestEndpoint: string;
+    /** API do Manager: <baseUrl>/v1/manager */
+    managerBaseUrl: string;
+}
+interface ConfigInput {
+    clientSecret: string;
+}
+/** Resolve o clientSecret nos endpoints do Monitor e do Manager. */
+declare function resolveConfig(options: ConfigInput, prefix?: string): ResolvedConfig;
+
+type BreadcrumbInput = Omit<Breadcrumb, 'timestamp'> & {
+    timestamp?: string;
+};
+/** Estado contextual anexado aos eventos: tags, usuário, contexts, extras e breadcrumbs. */
+declare class Scope {
+    tags: Record<string, string>;
+    user?: EventUser;
+    contexts: Record<string, Record<string, unknown>>;
+    extra: Record<string, unknown>;
+    level?: Severity;
+    fingerprint?: string[];
+    breadcrumbs: Breadcrumb[];
+    setTag(key: string, value: string): this;
+    setTags(tags: Record<string, string>): this;
+    setUser(user: EventUser | null): this;
+    setContext(name: string, context: Record<string, unknown> | null): this;
+    setExtra(key: string, value: unknown): this;
+    setExtras(extras: Record<string, unknown>): this;
+    setLevel(level: Severity): this;
+    setFingerprint(fingerprint: string[]): this;
+    addBreadcrumb(crumb: BreadcrumbInput, maxBreadcrumbs: number): this;
+    clearBreadcrumbs(): this;
+    clone(): Scope;
+}
+
+interface Logger {
+    debug: (...args: unknown[]) => void;
+    warn: (...args: unknown[]) => void;
+    error: (...args: unknown[]) => void;
+}
+
+declare class Client {
+    readonly options: InitOptions;
+    readonly config: ResolvedConfig;
+    readonly logger: Logger;
+    private readonly transport;
+    constructor(options: InitOptions);
+    captureException(error: unknown, hint: CaptureHint | undefined, scope: Scope): string;
+    captureMessage(message: string, level: Severity, hint: CaptureHint | undefined, scope: Scope): string;
+    captureEvent(event: EventPayload, hint: CaptureHint | undefined, scope: Scope): string;
+    private prepareEvent;
+    sendTransaction(payload: TransactionPayload): void;
+    sendCheckIn(payload: CheckInPayload): void;
+    sendHeartbeat(payload: HeartbeatPayload): void;
+    flush(timeoutMs?: number): Promise<boolean>;
+    close(timeoutMs?: number): Promise<boolean>;
+}
+
+declare class Span {
+    private readonly transaction;
+    readonly parentSpanId: string;
+    readonly op?: string | undefined;
+    readonly description?: string | undefined;
+    readonly spanId: string;
+    readonly startTimestamp: string;
+    status: SpanStatus;
+    endTimestamp?: string;
+    data?: Record<string, unknown>;
+    constructor(transaction: Transaction, parentSpanId: string, op?: string | undefined, description?: string | undefined);
+    setStatus(status: SpanStatus): this;
+    setData(key: string, value: unknown): this;
+    /** Span aninhado (filho deste span). */
+    startChild(op?: string, description?: string): Span;
+    finish(): void;
+    toJSON(): SpanData;
+}
+/**
+ * Uma unidade de trabalho nomeada (ex.: uma execução de rotina, uma sincronização).
+ * Spans filhos medem as etapas internas (chamadas HTTP, queries, etc.).
+ */
+declare class Transaction {
+    private readonly client;
+    name: string;
+    readonly op?: string | undefined;
+    private readonly sampled;
+    /** Correlaciona a uma execução do Manager — preenchido automaticamente em ctx.tx */
+    private readonly runId?;
+    readonly eventId: string;
+    readonly spanId: string;
+    readonly startTimestamp: string;
+    status: string;
+    private readonly spans;
+    private readonly tags;
+    private finished;
+    constructor(client: Client | undefined, name: string, op?: string | undefined, sampled?: boolean, 
+    /** Correlaciona a uma execução do Manager — preenchido automaticamente em ctx.tx */
+    runId?: string | undefined);
+    createSpan(parentSpanId: string, op?: string, description?: string): Span;
+    /** Span direto da transaction. */
+    startChild(op?: string, description?: string): Span;
+    setTag(key: string, value: string): this;
+    setStatus(status: string): this;
+    setName(name: string): this;
+    finish(): void;
+}
+
 /** Opções do Manager dentro de `init({ manager: ... })`. Credencial (clientSecret), identidade (instanceId) e debug vêm do init. */
 interface ManagerOptions {
     /** Intervalo entre polls sem trabalho. Default: 5_000 (mínimo 1_000) */
@@ -38,6 +151,8 @@ interface ManagerAgentOptions extends ManagerOptions {
     instanceId: string;
     /** Loga atividade do SDK no console */
     debug?: boolean;
+    /** Client do Monitor compartilhado — usado para enviar a transaction de performance de cada run (ctx.tx) */
+    client?: Client;
 }
 interface RunLogger {
     debug(message: string): void;
@@ -50,6 +165,12 @@ interface RunContext {
     task: string;
     /** Log bufferizado — enviado ao servidor em PATCHes incrementais com throttle */
     log: RunLogger;
+    /**
+     * Transaction de performance desta execução — já correlacionada à run e finalizada
+     * automaticamente ao fim do handler. Use `ctx.tx.startChild(op, description)` pra medir
+     * as etapas (steps) da task; elas aparecem como waterfall na aba de performance da execução.
+     */
+    tx: Transaction;
     /** Dispara em cancelamento (run cancelada no app), timeout ou shutdown — cancelamento cooperativo */
     signal: AbortSignal;
     /**
@@ -112,115 +233,6 @@ interface CaptureHint {
     fingerprint?: string[];
 }
 
-/** API oficial da Hobots — o SDK sempre fala com ela em produção. */
-declare const DEFAULT_BASE_URL = "https://api2.hobots.app";
-interface ResolvedConfig {
-    /** Client Secret do projeto (enviado como Authorization: Bearer, nunca na URL) */
-    key: string;
-    baseUrl: string;
-    /** Ingestão do Monitor: <baseUrl>/v1/ingest */
-    ingestEndpoint: string;
-    /** API do Manager: <baseUrl>/v1/manager */
-    managerBaseUrl: string;
-}
-interface ConfigInput {
-    clientSecret: string;
-}
-/** Resolve o clientSecret nos endpoints do Monitor e do Manager. */
-declare function resolveConfig(options: ConfigInput, prefix?: string): ResolvedConfig;
-
-type BreadcrumbInput = Omit<Breadcrumb, 'timestamp'> & {
-    timestamp?: string;
-};
-/** Estado contextual anexado aos eventos: tags, usuário, contexts, extras e breadcrumbs. */
-declare class Scope {
-    tags: Record<string, string>;
-    user?: EventUser;
-    contexts: Record<string, Record<string, unknown>>;
-    extra: Record<string, unknown>;
-    level?: Severity;
-    fingerprint?: string[];
-    breadcrumbs: Breadcrumb[];
-    setTag(key: string, value: string): this;
-    setTags(tags: Record<string, string>): this;
-    setUser(user: EventUser | null): this;
-    setContext(name: string, context: Record<string, unknown> | null): this;
-    setExtra(key: string, value: unknown): this;
-    setExtras(extras: Record<string, unknown>): this;
-    setLevel(level: Severity): this;
-    setFingerprint(fingerprint: string[]): this;
-    addBreadcrumb(crumb: BreadcrumbInput, maxBreadcrumbs: number): this;
-    clearBreadcrumbs(): this;
-    clone(): Scope;
-}
-
-interface Logger {
-    debug: (...args: unknown[]) => void;
-    warn: (...args: unknown[]) => void;
-    error: (...args: unknown[]) => void;
-}
-
-declare class Client {
-    readonly options: InitOptions;
-    readonly config: ResolvedConfig;
-    readonly logger: Logger;
-    private readonly transport;
-    constructor(options: InitOptions);
-    captureException(error: unknown, hint: CaptureHint | undefined, scope: Scope): string;
-    captureMessage(message: string, level: Severity, hint: CaptureHint | undefined, scope: Scope): string;
-    captureEvent(event: EventPayload, hint: CaptureHint | undefined, scope: Scope): string;
-    private prepareEvent;
-    sendTransaction(payload: TransactionPayload): void;
-    sendCheckIn(payload: CheckInPayload): void;
-    sendHeartbeat(payload: HeartbeatPayload): void;
-    flush(timeoutMs?: number): Promise<boolean>;
-    close(timeoutMs?: number): Promise<boolean>;
-}
-
-declare class Span {
-    private readonly transaction;
-    readonly parentSpanId: string;
-    readonly op?: string | undefined;
-    readonly description?: string | undefined;
-    readonly spanId: string;
-    readonly startTimestamp: string;
-    status: string;
-    endTimestamp?: string;
-    data?: Record<string, unknown>;
-    constructor(transaction: Transaction, parentSpanId: string, op?: string | undefined, description?: string | undefined);
-    setStatus(status: string): this;
-    setData(key: string, value: unknown): this;
-    /** Span aninhado (filho deste span). */
-    startChild(op?: string, description?: string): Span;
-    finish(): void;
-    toJSON(): SpanData;
-}
-/**
- * Uma unidade de trabalho nomeada (ex.: uma execução de rotina, uma sincronização).
- * Spans filhos medem as etapas internas (chamadas HTTP, queries, etc.).
- */
-declare class Transaction {
-    private readonly client;
-    name: string;
-    readonly op?: string | undefined;
-    private readonly sampled;
-    readonly eventId: string;
-    readonly spanId: string;
-    readonly startTimestamp: string;
-    status: string;
-    private readonly spans;
-    private readonly tags;
-    private finished;
-    constructor(client: Client | undefined, name: string, op?: string | undefined, sampled?: boolean);
-    createSpan(parentSpanId: string, op?: string, description?: string): Span;
-    /** Span direto da transaction. */
-    startChild(op?: string, description?: string): Span;
-    setTag(key: string, value: string): this;
-    setStatus(status: string): this;
-    setName(name: string): this;
-    finish(): void;
-}
-
 interface CheckInOptions {
     monitorSlug: string;
     status: CheckInStatus;
@@ -284,6 +296,7 @@ declare class ManagerAgent {
     private readonly registry;
     readonly logger: Logger;
     private readonly api;
+    private readonly client;
     private readonly pollIntervalMs;
     private readonly concurrency;
     private readonly instanceId;