@alva-ai/toolkit 0.4.3 → 0.7.0-beta.0

package/dist/index.d.cts

@@ -5,7 +5,7 @@ interface AlvaClientConfig {
     arraysBaseUrl?: string;
 }
 interface UserProfile {
-    id: number;
+    id: string;
     username: string;
     subscription_tier: 'free' | 'pro';
     telegram_username: string | null;
@@ -161,6 +161,14 @@ interface CronjobRun {
     duration_ms: number;
     credits_used: number;
     created_at: string;
+    /**
+     * Hatchet workflow run id captured at trigger time. Populated for runs
+     * persisted by recent worker binaries (both naturally-scheduled ticks and
+     * triggered runs); empty for older rows. External callers that issued
+     * `deploy.trigger()` filter by this field to find the run their request
+     * produced.
+     */
+    workflow_run_id?: string;
 }
 interface CronjobRunStats {
     total_runs: number;
@@ -177,6 +185,15 @@ interface CronjobRunsListResponse {
 interface CronjobRunLogsResponse {
     logs: string;
 }
+interface CronjobTriggerResponse {
+    /**
+     * Hatchet workflow run id at enqueue. Async — the persisted
+     * `cronjob_runs` row appears only after the worker finishes the run.
+     * Callers verify completion by polling `deploy.listRuns({cronjob_id})`
+     * and matching `runs[].workflow_run_id` against this value.
+     */
+    workflow_run_id: string;
+}
 interface FeedReleaseRequest {
     name: string;
     version: string;
@@ -201,6 +218,12 @@ interface PlaybookDraftRequest {
         feed_major?: number;
     }>;
     trading_symbols?: string[];
+    /**
+     * Optional source-template reference in "username/name" form (matches
+     * playbook_templates PK, e.g. "alva/screener"). Persisted set-once on
+     * the playbook's first draft; subsequent drafts ignore the field.
+     */
+    template_id?: string;
 }
 interface PlaybookDraftResponse {
     playbook_id: number;
@@ -216,6 +239,14 @@ interface PlaybookReleaseRequest {
         feed_major?: number;
     }>;
     changelog: string;
+    /**
+     * Owner-attested README location. Server validates the value is one of:
+     *   - relative: `<name>/README.md`
+     *   - absolute: `/alva/home/<username>/playbooks/<name>/README.md`
+     * The owner is responsible for placing the README at that path on ALFS
+     * before publish; the server does not write the file.
+     */
+    readme_url: string;
 }
 interface PlaybookReleaseResponse {
     playbook_id: number;
@@ -288,6 +319,9 @@ interface ScreenshotParams {
     url: string;
     selector?: string;
     xpath?: string;
+    compress?: boolean;
+    compressQuality?: number;
+    compressMaxWidth?: number;
 }
 interface TradingAccount {
     id: string;
@@ -572,6 +606,21 @@ declare class DeployResource {
     resume(params: {
         id: number;
     }): Promise<void>;
+    /**
+     * Fire the cronjob workflow once, immediately, bypassing the schedule.
+     * Async — returns the Hatchet workflow run id at enqueue. The
+     * `cronjob_runs` row appears only after the worker finishes the run;
+     * callers verify completion by polling `listRuns({cronjob_id})` and
+     * matching `runs[].workflow_run_id` against the returned id.
+     *
+     * Surfaces backend status as HTTP errors (handled by AlvaClient):
+     * - 404 not found / cross-user
+     * - 412 cronjob is paused (resume before triggering)
+     * - 503 worker workflow handle not yet connected (startup race)
+     */
+    trigger(params: {
+        id: number;
+    }): Promise<CronjobTriggerResponse>;
     listRuns(params: CronjobRunsListParams): Promise<CronjobRunsListResponse>;
     getRunLogs(params: {
         cronjob_id: number;
@@ -618,16 +667,40 @@ declare class SdkDocsResource {
     }): Promise<PartitionSummaryResponse>;
 }
 
+type SkillEndpointTier = 'public' | 'alternative' | 'unstructured';
+interface SkillEndpointMetadata {
+    skill: string;
+    file: string;
+    method: string;
+    path: string;
+    tier: SkillEndpointTier;
+    required_subscription_tier: 'free' | 'pro';
+    access: 'free_and_pro' | 'pro_only';
+    pro_required: boolean;
+}
+
+type SkillTierCounts = Partial<Record<SkillEndpointTier, number>>;
+
+interface SkillMetadata {
+    endpoint_count: number;
+    endpoint_tier_counts: SkillTierCounts;
+    pro_count: number;
+}
 interface SkillSummary {
     name: string;
     description: string;
+    metadata?: SkillMetadata;
+    endpoint_tier_counts?: SkillTierCounts;
 }
 interface SkillDoc {
     name: string;
     description: string;
     content: string;
+    metadata?: SkillMetadata | SkillEndpointMetadata;
+    endpoint_metadata?: SkillEndpointMetadata[];
+    endpoint_tier_counts?: SkillTierCounts;
 }
-declare class SkillsResource {
+declare class DataSkillsResource {
     private client;
     constructor(client: AlvaClient);
     list(): Promise<{
@@ -642,6 +715,47 @@ declare class SkillsResource {
     }): Promise<SkillDoc>;
 }
 
+interface PlaybookSkillSummary {
+    username: string;
+    name: string;
+    description: string;
+    tags: string[];
+    creator_uid: number;
+    updated_at: string;
+}
+interface PlaybookSkillFileMeta {
+    path: string;
+    size_bytes: number;
+}
+interface PlaybookSkillMeta extends PlaybookSkillSummary {
+    files: PlaybookSkillFileMeta[];
+}
+interface PlaybookSkillFile {
+    username: string;
+    name: string;
+    path: string;
+    content: string;
+    updated_at: string;
+}
+interface PlaybookSkillTagEntry {
+    name: string;
+}
+declare class PlaybookSkillsResource {
+    private client;
+    constructor(client: AlvaClient);
+    list(params?: {
+        tag?: string;
+        username?: string;
+    }): Promise<{
+        skills: PlaybookSkillSummary[];
+    }>;
+    tags(): Promise<{
+        tags: PlaybookSkillTagEntry[];
+    }>;
+    get(id: string): Promise<PlaybookSkillMeta>;
+    file(id: string, path: string): Promise<PlaybookSkillFile>;
+}
+
 declare class CommentsResource {
     private client;
     constructor(client: AlvaClient);
@@ -824,7 +938,8 @@ declare class AlvaClient {
     private _release?;
     private _secrets?;
     private _sdk?;
-    private _skills?;
+    private _dataSkills?;
+    private _playbookSkills?;
     private _comments?;
     private _remix?;
     private _screenshot?;
@@ -841,7 +956,8 @@ declare class AlvaClient {
     get release(): ReleaseResource;
     get secrets(): SecretsResource;
     get sdk(): SdkDocsResource;
-    get skills(): SkillsResource;
+    get dataSkills(): DataSkillsResource;
+    get playbookSkills(): PlaybookSkillsResource;
     get comments(): CommentsResource;
     get remix(): RemixResource;
     get screenshot(): ScreenshotResource;
@@ -864,4 +980,4 @@ declare class AlvaError extends Error {
 /** SDK version, injected at build time from package.json. */
 declare const VERSION: string;
 
-export { AlvaClient, type AlvaClientConfig, AlvaError, type ChannelGroupAdminInfo, type ChannelGroupCallerInfo, type ChannelGroupSubscription, type ChannelGroupSubscriptionContextResponse, type ChannelGroupSubscriptionListResponse, type ChannelGroupSubscriptionMutationParams, type ChannelGroupSubscriptionMutationResponse, type ChannelGroupSubscriptionSessionParams, type ChannelGroupSubscriptionTarget, type ChannelGroupSubscriptionTargetType, type FsChmodParams, type FsCopyParams, type FsEntry, type FsGrantParams, type FsMkdirParams, type FsRawWriteParams, type FsReadParams, type FsReaddirParams, type FsReaddirResponse, type FsReadlinkParams, type FsRemoveParams, type FsRenameParams, type FsRevokeParams, type FsStat, type FsSymlinkParams, type FsWriteParams, type FsWriteResponse, VERSION };
+export { AlvaClient, type AlvaClientConfig, AlvaError, type ChannelGroupAdminInfo, type ChannelGroupCallerInfo, type ChannelGroupSubscription, type ChannelGroupSubscriptionContextResponse, type ChannelGroupSubscriptionListResponse, type ChannelGroupSubscriptionMutationParams, type ChannelGroupSubscriptionMutationResponse, type ChannelGroupSubscriptionSessionParams, type ChannelGroupSubscriptionTarget, type ChannelGroupSubscriptionTargetType, type FsChmodParams, type FsCopyParams, type FsEntry, type FsGrantParams, type FsMkdirParams, type FsRawWriteParams, type FsReadParams, type FsReaddirParams, type FsReaddirResponse, type FsReadlinkParams, type FsRemoveParams, type FsRenameParams, type FsRevokeParams, type FsStat, type FsSymlinkParams, type FsWriteParams, type FsWriteResponse, type SkillDoc, type SkillEndpointMetadata, type SkillEndpointTier, type SkillMetadata, type SkillSummary, VERSION };

package/dist/index.d.ts

@@ -5,7 +5,7 @@ interface AlvaClientConfig {
     arraysBaseUrl?: string;
 }
 interface UserProfile {
-    id: number;
+    id: string;
     username: string;
     subscription_tier: 'free' | 'pro';
     telegram_username: string | null;
@@ -161,6 +161,14 @@ interface CronjobRun {
     duration_ms: number;
     credits_used: number;
     created_at: string;
+    /**
+     * Hatchet workflow run id captured at trigger time. Populated for runs
+     * persisted by recent worker binaries (both naturally-scheduled ticks and
+     * triggered runs); empty for older rows. External callers that issued
+     * `deploy.trigger()` filter by this field to find the run their request
+     * produced.
+     */
+    workflow_run_id?: string;
 }
 interface CronjobRunStats {
     total_runs: number;
@@ -177,6 +185,15 @@ interface CronjobRunsListResponse {
 interface CronjobRunLogsResponse {
     logs: string;
 }
+interface CronjobTriggerResponse {
+    /**
+     * Hatchet workflow run id at enqueue. Async — the persisted
+     * `cronjob_runs` row appears only after the worker finishes the run.
+     * Callers verify completion by polling `deploy.listRuns({cronjob_id})`
+     * and matching `runs[].workflow_run_id` against this value.
+     */
+    workflow_run_id: string;
+}
 interface FeedReleaseRequest {
     name: string;
     version: string;
@@ -201,6 +218,12 @@ interface PlaybookDraftRequest {
         feed_major?: number;
     }>;
     trading_symbols?: string[];
+    /**
+     * Optional source-template reference in "username/name" form (matches
+     * playbook_templates PK, e.g. "alva/screener"). Persisted set-once on
+     * the playbook's first draft; subsequent drafts ignore the field.
+     */
+    template_id?: string;
 }
 interface PlaybookDraftResponse {
     playbook_id: number;
@@ -216,6 +239,14 @@ interface PlaybookReleaseRequest {
         feed_major?: number;
     }>;
     changelog: string;
+    /**
+     * Owner-attested README location. Server validates the value is one of:
+     *   - relative: `<name>/README.md`
+     *   - absolute: `/alva/home/<username>/playbooks/<name>/README.md`
+     * The owner is responsible for placing the README at that path on ALFS
+     * before publish; the server does not write the file.
+     */
+    readme_url: string;
 }
 interface PlaybookReleaseResponse {
     playbook_id: number;
@@ -288,6 +319,9 @@ interface ScreenshotParams {
     url: string;
     selector?: string;
     xpath?: string;
+    compress?: boolean;
+    compressQuality?: number;
+    compressMaxWidth?: number;
 }
 interface TradingAccount {
     id: string;
@@ -572,6 +606,21 @@ declare class DeployResource {
     resume(params: {
         id: number;
     }): Promise<void>;
+    /**
+     * Fire the cronjob workflow once, immediately, bypassing the schedule.
+     * Async — returns the Hatchet workflow run id at enqueue. The
+     * `cronjob_runs` row appears only after the worker finishes the run;
+     * callers verify completion by polling `listRuns({cronjob_id})` and
+     * matching `runs[].workflow_run_id` against the returned id.
+     *
+     * Surfaces backend status as HTTP errors (handled by AlvaClient):
+     * - 404 not found / cross-user
+     * - 412 cronjob is paused (resume before triggering)
+     * - 503 worker workflow handle not yet connected (startup race)
+     */
+    trigger(params: {
+        id: number;
+    }): Promise<CronjobTriggerResponse>;
     listRuns(params: CronjobRunsListParams): Promise<CronjobRunsListResponse>;
     getRunLogs(params: {
         cronjob_id: number;
@@ -618,16 +667,40 @@ declare class SdkDocsResource {
     }): Promise<PartitionSummaryResponse>;
 }
 
+type SkillEndpointTier = 'public' | 'alternative' | 'unstructured';
+interface SkillEndpointMetadata {
+    skill: string;
+    file: string;
+    method: string;
+    path: string;
+    tier: SkillEndpointTier;
+    required_subscription_tier: 'free' | 'pro';
+    access: 'free_and_pro' | 'pro_only';
+    pro_required: boolean;
+}
+
+type SkillTierCounts = Partial<Record<SkillEndpointTier, number>>;
+
+interface SkillMetadata {
+    endpoint_count: number;
+    endpoint_tier_counts: SkillTierCounts;
+    pro_count: number;
+}
 interface SkillSummary {
     name: string;
     description: string;
+    metadata?: SkillMetadata;
+    endpoint_tier_counts?: SkillTierCounts;
 }
 interface SkillDoc {
     name: string;
     description: string;
     content: string;
+    metadata?: SkillMetadata | SkillEndpointMetadata;
+    endpoint_metadata?: SkillEndpointMetadata[];
+    endpoint_tier_counts?: SkillTierCounts;
 }
-declare class SkillsResource {
+declare class DataSkillsResource {
     private client;
     constructor(client: AlvaClient);
     list(): Promise<{
@@ -642,6 +715,47 @@ declare class SkillsResource {
     }): Promise<SkillDoc>;
 }
 
+interface PlaybookSkillSummary {
+    username: string;
+    name: string;
+    description: string;
+    tags: string[];
+    creator_uid: number;
+    updated_at: string;
+}
+interface PlaybookSkillFileMeta {
+    path: string;
+    size_bytes: number;
+}
+interface PlaybookSkillMeta extends PlaybookSkillSummary {
+    files: PlaybookSkillFileMeta[];
+}
+interface PlaybookSkillFile {
+    username: string;
+    name: string;
+    path: string;
+    content: string;
+    updated_at: string;
+}
+interface PlaybookSkillTagEntry {
+    name: string;
+}
+declare class PlaybookSkillsResource {
+    private client;
+    constructor(client: AlvaClient);
+    list(params?: {
+        tag?: string;
+        username?: string;
+    }): Promise<{
+        skills: PlaybookSkillSummary[];
+    }>;
+    tags(): Promise<{
+        tags: PlaybookSkillTagEntry[];
+    }>;
+    get(id: string): Promise<PlaybookSkillMeta>;
+    file(id: string, path: string): Promise<PlaybookSkillFile>;
+}
+
 declare class CommentsResource {
     private client;
     constructor(client: AlvaClient);
@@ -824,7 +938,8 @@ declare class AlvaClient {
     private _release?;
     private _secrets?;
     private _sdk?;
-    private _skills?;
+    private _dataSkills?;
+    private _playbookSkills?;
     private _comments?;
     private _remix?;
     private _screenshot?;
@@ -841,7 +956,8 @@ declare class AlvaClient {
     get release(): ReleaseResource;
     get secrets(): SecretsResource;
     get sdk(): SdkDocsResource;
-    get skills(): SkillsResource;
+    get dataSkills(): DataSkillsResource;
+    get playbookSkills(): PlaybookSkillsResource;
     get comments(): CommentsResource;
     get remix(): RemixResource;
     get screenshot(): ScreenshotResource;
@@ -864,4 +980,4 @@ declare class AlvaError extends Error {
 /** SDK version, injected at build time from package.json. */
 declare const VERSION: string;
 
-export { AlvaClient, type AlvaClientConfig, AlvaError, type ChannelGroupAdminInfo, type ChannelGroupCallerInfo, type ChannelGroupSubscription, type ChannelGroupSubscriptionContextResponse, type ChannelGroupSubscriptionListResponse, type ChannelGroupSubscriptionMutationParams, type ChannelGroupSubscriptionMutationResponse, type ChannelGroupSubscriptionSessionParams, type ChannelGroupSubscriptionTarget, type ChannelGroupSubscriptionTargetType, type FsChmodParams, type FsCopyParams, type FsEntry, type FsGrantParams, type FsMkdirParams, type FsRawWriteParams, type FsReadParams, type FsReaddirParams, type FsReaddirResponse, type FsReadlinkParams, type FsRemoveParams, type FsRenameParams, type FsRevokeParams, type FsStat, type FsSymlinkParams, type FsWriteParams, type FsWriteResponse, VERSION };
+export { AlvaClient, type AlvaClientConfig, AlvaError, type ChannelGroupAdminInfo, type ChannelGroupCallerInfo, type ChannelGroupSubscription, type ChannelGroupSubscriptionContextResponse, type ChannelGroupSubscriptionListResponse, type ChannelGroupSubscriptionMutationParams, type ChannelGroupSubscriptionMutationResponse, type ChannelGroupSubscriptionSessionParams, type ChannelGroupSubscriptionTarget, type ChannelGroupSubscriptionTargetType, type FsChmodParams, type FsCopyParams, type FsEntry, type FsGrantParams, type FsMkdirParams, type FsRawWriteParams, type FsReadParams, type FsReaddirParams, type FsReaddirResponse, type FsReadlinkParams, type FsRemoveParams, type FsRenameParams, type FsRevokeParams, type FsStat, type FsSymlinkParams, type FsWriteParams, type FsWriteResponse, type SkillDoc, type SkillEndpointMetadata, type SkillEndpointTier, type SkillMetadata, type SkillSummary, VERSION };