@ceki/sdk 1.12.0 → 1.14.0

package/dist/index.d.cts

@@ -242,14 +242,23 @@ declare class Browser {
         method: string;
         params?: Record<string, unknown>;
     }, timeout?: number): Promise<unknown>;
-    navigate(url: string, timeout?: number): Promise<{
+    private _humanizeForCall;
+    navigate(url: string, timeout?: number, opts?: {
+        human?: boolean;
+    }): Promise<{
         url: string;
         frameId?: string;
     }>;
-    click(x: number, y: number): Promise<void>;
+    click(x: number, y: number, opts?: {
+        human?: boolean;
+    }): Promise<void>;
     private _sendKeystroke;
-    type(text: string): Promise<void>;
-    scroll(opts?: ScrollOptions): Promise<void>;
+    type(text: string, opts?: {
+        human?: boolean;
+    }): Promise<void>;
+    scroll(opts?: ScrollOptions & {
+        human?: boolean;
+    }): Promise<void>;
     screenshot(opts?: ScreenshotOptions): Promise<{
         data: string;
     } | Buffer>;
@@ -418,4 +427,157 @@ declare class ChatSendFailed extends CekiBrowserError {
     constructor(status: number, messageText: string);
 }
 
-export { AuthError, Browser, BrowserChat, type BrowserOption, BrowserProfile, CaptchaError, type CaptchaOptions, type CaptchaResult, CaptchaTimeoutError, CdpUnrecoverable, CekiBrowserError, type ChatHistoryOptions, type ChatMessage, ChatSendFailed, Client, type ConnectOptions, ConnectionLost, HumanProfile, Humanizer, InsufficientFunds, type Match, NotOwner, type Profile, type ProfileExportOptions, ProviderDisconnected, ProviderOffline, RateLimitExceeded, type ReadReceipt, type RentOptions, type ScreenshotOptions, type ScrollOptions, SessionEnded, SessionExpired, type SessionInfo, SessionNotFound, type Snapshot, TimeoutError, TransportError, connect };
+declare const ROLE_REVIEWER = 5;
+declare const ROLE_QA = 6;
+type Benefitable = {
+    type: string;
+    value: number;
+};
+type ParticipantSpec = {
+    participable_id: number;
+    type: 'agent' | 'user' | string;
+    role_id: number;
+};
+declare class ContractError extends Error {
+    constructor(message: string);
+}
+/** Parse 'agent:N' / 'user:N' into {type, value}. Throws on malformed input. */
+declare function parseBenefitable(value: string | null | undefined): Benefitable | null;
+/** Parse 'agent:N' / 'user:N' into {participable_id, type, role_id}.
+ *
+ * Wire shape declared by the create-contract-event MCP tool schema:
+ * `participable_id` + `type` (short token: 'agent' or 'user') + `role_id`.
+ * The MCP tool drops any field it does not know about, so sending
+ * `participable_type` (FQCN) silently loses the type and the backend
+ * membership lookup defaults to user → misleading 422 "Participant must
+ * be a member of the contract". Send `type`.
+ */
+declare function parseParticipant(value: string | null | undefined, roleId: number): ParticipantSpec | null;
+/** Strip undefined and null values; keep 0, false, '', [], {}. */
+declare function cleanArgs<T extends Record<string, unknown>>(o: T): Partial<T>;
+/** Derive a short (<=60 char) label from a desc's first non-empty line. */
+declare function deriveLabel(desc: string | null | undefined): string;
+declare function contractIdsFromEnv(): string[];
+/** Injectable HTTP transport — vitest swaps this out in tests. */
+type HttpResponse = {
+    status: number;
+    text(): Promise<string>;
+    json(): Promise<unknown>;
+};
+interface HttpClient {
+    post(url: string, init: {
+        headers: Record<string, string>;
+        body: string;
+    }): Promise<HttpResponse>;
+    get(url: string, init: {
+        headers: Record<string, string>;
+    }): Promise<HttpResponse>;
+}
+type ContractClientOptions = {
+    endpoint?: string;
+    apiBase?: string;
+    token?: string;
+    http?: HttpClient;
+    timeoutMs?: number;
+};
+type CreateOptions = {
+    label: string;
+    type?: number;
+    status?: number;
+    kalScheduleId?: number;
+    start?: string;
+    end?: string;
+    timezone?: string;
+    date?: string;
+    duration?: number;
+    amount?: number;
+    currency?: string;
+    description?: string;
+    data?: Record<string, unknown>;
+    benefitable?: string;
+    reviewer?: string;
+    qa?: string;
+    participants?: ParticipantSpec[];
+};
+type CommentOptions = {
+    label?: string;
+    type?: number;
+    status?: number;
+    start?: string;
+    end?: string;
+    date?: string;
+    duration?: number;
+    amount?: number;
+    currency?: string;
+    description?: string;
+    benefitable?: string;
+};
+type ProposeOptions = {
+    status?: number;
+    label?: string;
+    description?: string;
+    start?: string;
+    end?: string;
+    date?: string;
+    duration?: number;
+    amount?: number;
+    currency?: string;
+    benefitable?: string;
+};
+type ProgressOptions = {
+    status?: number;
+    desc: string;
+};
+type ProgressResult = {
+    status_correction: unknown;
+    comment: unknown;
+};
+declare class ContractClient {
+    readonly endpoint: string;
+    readonly apiBase: string;
+    readonly token: string;
+    private http;
+    constructor(opts?: ContractClientOptions);
+    private headers;
+    private rpc;
+    /** Call MCP tool; unwrap content[].text (JSON-parsed) or structuredContent. */
+    call(tool: string, args?: Record<string, unknown>): Promise<unknown>;
+    tools(): Promise<unknown>;
+    raw(tool: string, args?: Record<string, unknown>): Promise<unknown>;
+    listContracts(): Promise<unknown>;
+    members(contractId: number): Promise<unknown>;
+    tasks(contractId: number): Promise<unknown>;
+    myJobs(): Promise<unknown>;
+    task(eventId: number): Promise<unknown>;
+    children(eventId: number): Promise<unknown>;
+    history(eventId: number, opts?: {
+        limit?: number;
+    }): Promise<unknown>;
+    create(contractId: number, opts: CreateOptions): Promise<unknown>;
+    comment(eventId: number, opts?: CommentOptions): Promise<unknown>;
+    propose(eventId: number, opts?: ProposeOptions): Promise<unknown>;
+    /** Status correction (optional) + progress comment in one shot.
+     *
+     * The event's own description is NOT touched. `desc` becomes the
+     * body of a child comment-event, not a label/description overwrite
+     * on the parent event. Use this for Hand/QA/Reviewer progress
+     * reports — `propose --desc` would clobber the parent spec.
+     */
+    progress(eventId: number, opts: ProgressOptions): Promise<ProgressResult>;
+    vote(eventId: number, ids: number[], vote: boolean): Promise<unknown>;
+    /** GET /agent/polling. Returns [] on 429 (rate-limit, 10/min/token). */
+    poll(): Promise<unknown[]>;
+}
+
+type TimelogClientOptions = ContractClientOptions & {
+    contract?: ContractClient;
+};
+declare class TimelogClient {
+    private c;
+    constructor(opts?: TimelogClientOptions);
+    start(eventId: number): Promise<unknown>;
+    stop(eventId: number, label?: string): Promise<unknown>;
+    check(eventId: number): Promise<unknown>;
+}
+
+export { AuthError, type Benefitable, Browser, BrowserChat, type BrowserOption, BrowserProfile, CaptchaError, type CaptchaOptions, type CaptchaResult, CaptchaTimeoutError, CdpUnrecoverable, CekiBrowserError, type ChatHistoryOptions, type ChatMessage, ChatSendFailed, Client, type CommentOptions, type ConnectOptions, ConnectionLost, ContractClient, type ContractClientOptions, ContractError, type CreateOptions, type HttpClient, type HttpResponse, HumanProfile, Humanizer, InsufficientFunds, type Match, NotOwner, type ParticipantSpec, type Profile, type ProfileExportOptions, type ProgressOptions, type ProgressResult, type ProposeOptions, ProviderDisconnected, ProviderOffline, ROLE_QA, ROLE_REVIEWER, RateLimitExceeded, type ReadReceipt, type RentOptions, type ScreenshotOptions, type ScrollOptions, SessionEnded, SessionExpired, type SessionInfo, SessionNotFound, type Snapshot, TimelogClient, type TimelogClientOptions, TimeoutError, TransportError, cleanArgs, connect, contractIdsFromEnv, deriveLabel, parseBenefitable, parseParticipant };

package/dist/index.d.ts

@@ -242,14 +242,23 @@ declare class Browser {
         method: string;
         params?: Record<string, unknown>;
     }, timeout?: number): Promise<unknown>;
-    navigate(url: string, timeout?: number): Promise<{
+    private _humanizeForCall;
+    navigate(url: string, timeout?: number, opts?: {
+        human?: boolean;
+    }): Promise<{
         url: string;
         frameId?: string;
     }>;
-    click(x: number, y: number): Promise<void>;
+    click(x: number, y: number, opts?: {
+        human?: boolean;
+    }): Promise<void>;
     private _sendKeystroke;
-    type(text: string): Promise<void>;
-    scroll(opts?: ScrollOptions): Promise<void>;
+    type(text: string, opts?: {
+        human?: boolean;
+    }): Promise<void>;
+    scroll(opts?: ScrollOptions & {
+        human?: boolean;
+    }): Promise<void>;
     screenshot(opts?: ScreenshotOptions): Promise<{
         data: string;
     } | Buffer>;
@@ -418,4 +427,157 @@ declare class ChatSendFailed extends CekiBrowserError {
     constructor(status: number, messageText: string);
 }
 
-export { AuthError, Browser, BrowserChat, type BrowserOption, BrowserProfile, CaptchaError, type CaptchaOptions, type CaptchaResult, CaptchaTimeoutError, CdpUnrecoverable, CekiBrowserError, type ChatHistoryOptions, type ChatMessage, ChatSendFailed, Client, type ConnectOptions, ConnectionLost, HumanProfile, Humanizer, InsufficientFunds, type Match, NotOwner, type Profile, type ProfileExportOptions, ProviderDisconnected, ProviderOffline, RateLimitExceeded, type ReadReceipt, type RentOptions, type ScreenshotOptions, type ScrollOptions, SessionEnded, SessionExpired, type SessionInfo, SessionNotFound, type Snapshot, TimeoutError, TransportError, connect };
+declare const ROLE_REVIEWER = 5;
+declare const ROLE_QA = 6;
+type Benefitable = {
+    type: string;
+    value: number;
+};
+type ParticipantSpec = {
+    participable_id: number;
+    type: 'agent' | 'user' | string;
+    role_id: number;
+};
+declare class ContractError extends Error {
+    constructor(message: string);
+}
+/** Parse 'agent:N' / 'user:N' into {type, value}. Throws on malformed input. */
+declare function parseBenefitable(value: string | null | undefined): Benefitable | null;
+/** Parse 'agent:N' / 'user:N' into {participable_id, type, role_id}.
+ *
+ * Wire shape declared by the create-contract-event MCP tool schema:
+ * `participable_id` + `type` (short token: 'agent' or 'user') + `role_id`.
+ * The MCP tool drops any field it does not know about, so sending
+ * `participable_type` (FQCN) silently loses the type and the backend
+ * membership lookup defaults to user → misleading 422 "Participant must
+ * be a member of the contract". Send `type`.
+ */
+declare function parseParticipant(value: string | null | undefined, roleId: number): ParticipantSpec | null;
+/** Strip undefined and null values; keep 0, false, '', [], {}. */
+declare function cleanArgs<T extends Record<string, unknown>>(o: T): Partial<T>;
+/** Derive a short (<=60 char) label from a desc's first non-empty line. */
+declare function deriveLabel(desc: string | null | undefined): string;
+declare function contractIdsFromEnv(): string[];
+/** Injectable HTTP transport — vitest swaps this out in tests. */
+type HttpResponse = {
+    status: number;
+    text(): Promise<string>;
+    json(): Promise<unknown>;
+};
+interface HttpClient {
+    post(url: string, init: {
+        headers: Record<string, string>;
+        body: string;
+    }): Promise<HttpResponse>;
+    get(url: string, init: {
+        headers: Record<string, string>;
+    }): Promise<HttpResponse>;
+}
+type ContractClientOptions = {
+    endpoint?: string;
+    apiBase?: string;
+    token?: string;
+    http?: HttpClient;
+    timeoutMs?: number;
+};
+type CreateOptions = {
+    label: string;
+    type?: number;
+    status?: number;
+    kalScheduleId?: number;
+    start?: string;
+    end?: string;
+    timezone?: string;
+    date?: string;
+    duration?: number;
+    amount?: number;
+    currency?: string;
+    description?: string;
+    data?: Record<string, unknown>;
+    benefitable?: string;
+    reviewer?: string;
+    qa?: string;
+    participants?: ParticipantSpec[];
+};
+type CommentOptions = {
+    label?: string;
+    type?: number;
+    status?: number;
+    start?: string;
+    end?: string;
+    date?: string;
+    duration?: number;
+    amount?: number;
+    currency?: string;
+    description?: string;
+    benefitable?: string;
+};
+type ProposeOptions = {
+    status?: number;
+    label?: string;
+    description?: string;
+    start?: string;
+    end?: string;
+    date?: string;
+    duration?: number;
+    amount?: number;
+    currency?: string;
+    benefitable?: string;
+};
+type ProgressOptions = {
+    status?: number;
+    desc: string;
+};
+type ProgressResult = {
+    status_correction: unknown;
+    comment: unknown;
+};
+declare class ContractClient {
+    readonly endpoint: string;
+    readonly apiBase: string;
+    readonly token: string;
+    private http;
+    constructor(opts?: ContractClientOptions);
+    private headers;
+    private rpc;
+    /** Call MCP tool; unwrap content[].text (JSON-parsed) or structuredContent. */
+    call(tool: string, args?: Record<string, unknown>): Promise<unknown>;
+    tools(): Promise<unknown>;
+    raw(tool: string, args?: Record<string, unknown>): Promise<unknown>;
+    listContracts(): Promise<unknown>;
+    members(contractId: number): Promise<unknown>;
+    tasks(contractId: number): Promise<unknown>;
+    myJobs(): Promise<unknown>;
+    task(eventId: number): Promise<unknown>;
+    children(eventId: number): Promise<unknown>;
+    history(eventId: number, opts?: {
+        limit?: number;
+    }): Promise<unknown>;
+    create(contractId: number, opts: CreateOptions): Promise<unknown>;
+    comment(eventId: number, opts?: CommentOptions): Promise<unknown>;
+    propose(eventId: number, opts?: ProposeOptions): Promise<unknown>;
+    /** Status correction (optional) + progress comment in one shot.
+     *
+     * The event's own description is NOT touched. `desc` becomes the
+     * body of a child comment-event, not a label/description overwrite
+     * on the parent event. Use this for Hand/QA/Reviewer progress
+     * reports — `propose --desc` would clobber the parent spec.
+     */
+    progress(eventId: number, opts: ProgressOptions): Promise<ProgressResult>;
+    vote(eventId: number, ids: number[], vote: boolean): Promise<unknown>;
+    /** GET /agent/polling. Returns [] on 429 (rate-limit, 10/min/token). */
+    poll(): Promise<unknown[]>;
+}
+
+type TimelogClientOptions = ContractClientOptions & {
+    contract?: ContractClient;
+};
+declare class TimelogClient {
+    private c;
+    constructor(opts?: TimelogClientOptions);
+    start(eventId: number): Promise<unknown>;
+    stop(eventId: number, label?: string): Promise<unknown>;
+    check(eventId: number): Promise<unknown>;
+}
+
+export { AuthError, type Benefitable, Browser, BrowserChat, type BrowserOption, BrowserProfile, CaptchaError, type CaptchaOptions, type CaptchaResult, CaptchaTimeoutError, CdpUnrecoverable, CekiBrowserError, type ChatHistoryOptions, type ChatMessage, ChatSendFailed, Client, type CommentOptions, type ConnectOptions, ConnectionLost, ContractClient, type ContractClientOptions, ContractError, type CreateOptions, type HttpClient, type HttpResponse, HumanProfile, Humanizer, InsufficientFunds, type Match, NotOwner, type ParticipantSpec, type Profile, type ProfileExportOptions, type ProgressOptions, type ProgressResult, type ProposeOptions, ProviderDisconnected, ProviderOffline, ROLE_QA, ROLE_REVIEWER, RateLimitExceeded, type ReadReceipt, type RentOptions, type ScreenshotOptions, type ScrollOptions, SessionEnded, SessionExpired, type SessionInfo, SessionNotFound, type Snapshot, TimelogClient, type TimelogClientOptions, TimeoutError, TransportError, cleanArgs, connect, contractIdsFromEnv, deriveLabel, parseBenefitable, parseParticipant };