@alva-ai/toolkit 0.2.1 → 0.4.0

package/dist/index.d.cts

@@ -2,12 +2,27 @@ interface AlvaClientConfig {
     viewer_token?: string;
     apiKey?: string;
     baseUrl?: string;
+    arraysBaseUrl?: string;
 }
 interface UserProfile {
     id: number;
     username: string;
     subscription_tier: 'free' | 'pro';
     telegram_username: string | null;
+    /** Caller's alfs home directory, e.g. `/alva/home/<username>`. */
+    home_path: string;
+}
+type SubscriptionTier = 'SUBSCRIPTION_TIER_UNSPECIFIED' | 'SUBSCRIPTION_TIER_FREE' | 'SUBSCRIPTION_TIER_PRO';
+interface EnsureArraysJwtResponse {
+    expires_at: number;
+    tier: SubscriptionTier;
+    renewed: boolean;
+}
+interface ArraysJwtStatusResponse {
+    exists: boolean;
+    expires_at: number;
+    tier: SubscriptionTier;
+    renewal_needed: boolean;
 }
 interface FsReadParams {
     path: string;
@@ -168,11 +183,14 @@ interface FeedReleaseRequest {
     cronjob_id: number;
     view_json?: Record<string, unknown>;
     description?: string;
+    changelog?: string;
 }
 interface FeedReleaseResponse {
     feed_id: number;
     name: string;
     feed_major: number;
+    /** Canonical alfs path: `/alva/home/<username>/feeds/<name>`. */
+    feed_path: string;
 }
 interface PlaybookDraftRequest {
     name: string;
@@ -183,11 +201,12 @@ interface PlaybookDraftRequest {
         feed_major?: number;
     }>;
     trading_symbols?: string[];
-    changelog?: string;
 }
 interface PlaybookDraftResponse {
     playbook_id: number;
     playbook_version_id: number;
+    /** Canonical alfs path: `/alva/home/<username>/playbooks/<name>`. */
+    playbook_path: string;
 }
 interface PlaybookReleaseRequest {
     name: string;
@@ -202,6 +221,8 @@ interface PlaybookReleaseResponse {
     playbook_id: number;
     version: string;
     published_url: string;
+    /** Canonical alfs path: `/alva/home/<username>/playbooks/<name>`. */
+    playbook_path: string;
 }
 interface CreateSecretRequest {
     name: string;
@@ -359,6 +380,91 @@ interface ExecuteSignalResult {
     orders: ExecuteSignalOrder[];
     error?: string;
 }
+interface NotificationListParams {
+    username: string;
+    name: string;
+    channel?: string;
+    /** `sent` / `failed` / `filtered`. */
+    status?: string;
+    /** Unix seconds; only notifications newer than this. */
+    since_time?: number;
+    /** Page size, default 50, max 200. */
+    first?: number;
+    /** Opaque cursor token from previous page's `next_cursor`. */
+    cursor?: string;
+}
+interface NotificationEvent {
+    id: string;
+    event_type: string;
+    user_id: string;
+    channel: string;
+    /** `sent` / `failed` / `filtered`. */
+    status: string;
+    /** Unix seconds. */
+    created_at: number;
+    message?: string;
+    error_msg?: string;
+    /** Present when notification is playbook-scoped. */
+    playbook_id?: string;
+    /** Present when notification is feed-scoped. */
+    feed_id?: string;
+}
+interface PlaybookNotificationListResponse {
+    items: NotificationEvent[];
+    /** Empty when there is no next page. */
+    next_cursor: string;
+    /** Canonical alfs path: `/alva/home/<username>/playbooks/<name>`. */
+    playbook_path: string;
+}
+interface FeedNotificationListResponse {
+    items: NotificationEvent[];
+    next_cursor: string;
+    /** Canonical alfs path: `/alva/home/<username>/feeds/<name>`. */
+    feed_path: string;
+}
+/**
+ * Identifies the asset a personal push subscription is keyed to.
+ * `PLAYBOOK` is the only target supported today; `FEED` is reserved for
+ * a future phase where users can subscribe to a feed independent of any
+ * playbook that consumes it.
+ */
+type PushTargetType = 'PLAYBOOK' | 'FEED' | 'UNSPECIFIED';
+interface PushTarget {
+    type: PushTargetType;
+    /** Numeric id encoded as a string (matches the rest of the SDK). */
+    id: string;
+}
+interface PushSubscription {
+    target: PushTarget;
+    /**
+     * `true` when the row is currently active. `false` means the user
+     * previously subscribed and then unsubscribed; the row is preserved
+     * so re-subscribe restores seniority via UPSERT-revive. Only present
+     * when `include_history=true` is passed to `list`.
+     */
+    subscribed: boolean;
+    created_at_ms: number;
+    updated_at_ms: number;
+}
+interface PushSubscriptionPlaybookParams {
+    username: string;
+    name: string;
+}
+interface PushSubscriptionListParams {
+    /** Default `false`. When `true`, include rows with `subscribed=false`. */
+    include_history?: boolean;
+}
+interface PushSubscriptionListResponse {
+    items: PushSubscription[];
+}
+interface SubscribePushTargetResponse {
+    subscription: PushSubscription;
+    /** Canonical alfs path: `/alva/home/<username>/playbooks/<name>`. */
+    playbook_path: string;
+}
+interface UnsubscribePushTargetResponse {
+    ok: true;
+}
 
 declare class FsResource {
     private client;
@@ -456,6 +562,30 @@ declare class SdkDocsResource {
     }): Promise<PartitionSummaryResponse>;
 }
 
+interface SkillSummary {
+    name: string;
+    description: string;
+}
+interface SkillDoc {
+    name: string;
+    description: string;
+    content: string;
+}
+declare class SkillsResource {
+    private client;
+    constructor(client: AlvaClient);
+    list(): Promise<{
+        skills: SkillSummary[];
+    }>;
+    summary(params: {
+        name: string;
+    }): Promise<SkillDoc>;
+    endpoint(params: {
+        name: string;
+        file: string;
+    }): Promise<SkillDoc>;
+}
+
 declare class CommentsResource {
     private client;
     constructor(client: AlvaClient);
@@ -526,14 +656,79 @@ declare class TradingResource {
     updateRiskRules(rules: TradingRiskRuleInput): Promise<TradingRiskRule>;
 }
 
+declare class ArraysJwtResource {
+    private client;
+    constructor(client: AlvaClient);
+    /** Idempotently sign-or-renew the Arrays JWT server-side. */
+    ensure(): Promise<EnsureArraysJwtResponse>;
+    /** Report the current Arrays JWT state for the authenticated user. */
+    status(): Promise<ArraysJwtStatusResponse>;
+}
+
+declare class NotificationsResource {
+    private client;
+    constructor(client: AlvaClient);
+    /**
+     * List the caller's notification history for one playbook
+     * `(username, name)`. Returns `NOT_FOUND` when the playbook is
+     * private or does not exist (the two cases are deliberately
+     * indistinguishable to prevent namespace enumeration).
+     */
+    listPlaybook(params: NotificationListParams): Promise<PlaybookNotificationListResponse>;
+    /**
+     * List the caller's notification history for one feed
+     * `(username, name)`. Authorization is alfs read on
+     * `/alva/home/<username>/feeds/<name>`.
+     */
+    listFeed(params: NotificationListParams): Promise<FeedNotificationListResponse>;
+}
+
+/**
+ * Personal push subscriptions — opt the caller in or out of personal
+ * DM/web push for a target. Independent of social follow:
+ *
+ *   - `subscribePlaybook` does not start following.
+ *   - `unsubscribePlaybook` does not unfollow.
+ *   - Following a playbook elsewhere will compound-subscribe automatically.
+ *
+ * Backed by alva-gateway REST (mirrors the GraphQL surface in
+ * `pkg/schema/push_subscription.graphql`).
+ */
+declare class PushSubscriptionsResource {
+    private client;
+    constructor(client: AlvaClient);
+    /**
+     * Opt into personal push for one playbook `(username, name)`.
+     * Idempotent. Auth: callers must be able to read the playbook
+     * (public/paid pass; private requires explicit alfs grant).
+     */
+    subscribePlaybook(params: PushSubscriptionPlaybookParams): Promise<SubscribePushTargetResponse>;
+    /**
+     * Soft-disable personal push for one playbook `(username, name)`.
+     * Does NOT remove any social follow. Idempotent.
+     */
+    unsubscribePlaybook(params: PushSubscriptionPlaybookParams): Promise<UnsubscribePushTargetResponse>;
+    /**
+     * List the caller's personal push subscriptions across all targets.
+     * Defaults to currently-active rows only; pass `include_history=true`
+     * to also return previously-unsubscribed rows.
+     */
+    list(params?: PushSubscriptionListParams): Promise<PushSubscriptionListResponse>;
+}
+
 interface RequestOptions {
     query?: Record<string, unknown>;
     body?: unknown;
     /** Send raw body with application/octet-stream content type (for binary writes). */
     rawBody?: BodyInit;
+    /** Override the base URL for this request (e.g. the Arrays data-tools endpoint). */
+    baseUrl?: string;
+    /** If true, skip attaching any Alva auth header (X-Alva-Api-Key / x-Playbook-Viewer). */
+    noAuth?: boolean;
 }
 declare class AlvaClient {
     readonly baseUrl: string;
+    readonly arraysBaseUrl: string;
     readonly viewer_token?: string;
     readonly apiKey?: string;
     private _fs?;
@@ -542,11 +737,15 @@ declare class AlvaClient {
     private _release?;
     private _secrets?;
     private _sdk?;
+    private _skills?;
     private _comments?;
     private _remix?;
     private _screenshot?;
     private _user?;
     private _trading?;
+    private _arraysJwt?;
+    private _notifications?;
+    private _pushSubscriptions?;
     constructor(config: AlvaClientConfig);
     get fs(): FsResource;
     get run(): RunResource;
@@ -554,11 +753,15 @@ declare class AlvaClient {
     get release(): ReleaseResource;
     get secrets(): SecretsResource;
     get sdk(): SdkDocsResource;
+    get skills(): SkillsResource;
     get comments(): CommentsResource;
     get remix(): RemixResource;
     get screenshot(): ScreenshotResource;
     get user(): UserResource;
     get trading(): TradingResource;
+    get arraysJwt(): ArraysJwtResource;
+    get notifications(): NotificationsResource;
+    get pushSubscriptions(): PushSubscriptionsResource;
     _requireAuth(): void;
     _request(method: string, path: string, options?: RequestOptions): Promise<unknown>;
 }

package/dist/index.d.ts

@@ -2,12 +2,27 @@ interface AlvaClientConfig {
     viewer_token?: string;
     apiKey?: string;
     baseUrl?: string;
+    arraysBaseUrl?: string;
 }
 interface UserProfile {
     id: number;
     username: string;
     subscription_tier: 'free' | 'pro';
     telegram_username: string | null;
+    /** Caller's alfs home directory, e.g. `/alva/home/<username>`. */
+    home_path: string;
+}
+type SubscriptionTier = 'SUBSCRIPTION_TIER_UNSPECIFIED' | 'SUBSCRIPTION_TIER_FREE' | 'SUBSCRIPTION_TIER_PRO';
+interface EnsureArraysJwtResponse {
+    expires_at: number;
+    tier: SubscriptionTier;
+    renewed: boolean;
+}
+interface ArraysJwtStatusResponse {
+    exists: boolean;
+    expires_at: number;
+    tier: SubscriptionTier;
+    renewal_needed: boolean;
 }
 interface FsReadParams {
     path: string;
@@ -168,11 +183,14 @@ interface FeedReleaseRequest {
     cronjob_id: number;
     view_json?: Record<string, unknown>;
     description?: string;
+    changelog?: string;
 }
 interface FeedReleaseResponse {
     feed_id: number;
     name: string;
     feed_major: number;
+    /** Canonical alfs path: `/alva/home/<username>/feeds/<name>`. */
+    feed_path: string;
 }
 interface PlaybookDraftRequest {
     name: string;
@@ -183,11 +201,12 @@ interface PlaybookDraftRequest {
         feed_major?: number;
     }>;
     trading_symbols?: string[];
-    changelog?: string;
 }
 interface PlaybookDraftResponse {
     playbook_id: number;
     playbook_version_id: number;
+    /** Canonical alfs path: `/alva/home/<username>/playbooks/<name>`. */
+    playbook_path: string;
 }
 interface PlaybookReleaseRequest {
     name: string;
@@ -202,6 +221,8 @@ interface PlaybookReleaseResponse {
     playbook_id: number;
     version: string;
     published_url: string;
+    /** Canonical alfs path: `/alva/home/<username>/playbooks/<name>`. */
+    playbook_path: string;
 }
 interface CreateSecretRequest {
     name: string;
@@ -359,6 +380,91 @@ interface ExecuteSignalResult {
     orders: ExecuteSignalOrder[];
     error?: string;
 }
+interface NotificationListParams {
+    username: string;
+    name: string;
+    channel?: string;
+    /** `sent` / `failed` / `filtered`. */
+    status?: string;
+    /** Unix seconds; only notifications newer than this. */
+    since_time?: number;
+    /** Page size, default 50, max 200. */
+    first?: number;
+    /** Opaque cursor token from previous page's `next_cursor`. */
+    cursor?: string;
+}
+interface NotificationEvent {
+    id: string;
+    event_type: string;
+    user_id: string;
+    channel: string;
+    /** `sent` / `failed` / `filtered`. */
+    status: string;
+    /** Unix seconds. */
+    created_at: number;
+    message?: string;
+    error_msg?: string;
+    /** Present when notification is playbook-scoped. */
+    playbook_id?: string;
+    /** Present when notification is feed-scoped. */
+    feed_id?: string;
+}
+interface PlaybookNotificationListResponse {
+    items: NotificationEvent[];
+    /** Empty when there is no next page. */
+    next_cursor: string;
+    /** Canonical alfs path: `/alva/home/<username>/playbooks/<name>`. */
+    playbook_path: string;
+}
+interface FeedNotificationListResponse {
+    items: NotificationEvent[];
+    next_cursor: string;
+    /** Canonical alfs path: `/alva/home/<username>/feeds/<name>`. */
+    feed_path: string;
+}
+/**
+ * Identifies the asset a personal push subscription is keyed to.
+ * `PLAYBOOK` is the only target supported today; `FEED` is reserved for
+ * a future phase where users can subscribe to a feed independent of any
+ * playbook that consumes it.
+ */
+type PushTargetType = 'PLAYBOOK' | 'FEED' | 'UNSPECIFIED';
+interface PushTarget {
+    type: PushTargetType;
+    /** Numeric id encoded as a string (matches the rest of the SDK). */
+    id: string;
+}
+interface PushSubscription {
+    target: PushTarget;
+    /**
+     * `true` when the row is currently active. `false` means the user
+     * previously subscribed and then unsubscribed; the row is preserved
+     * so re-subscribe restores seniority via UPSERT-revive. Only present
+     * when `include_history=true` is passed to `list`.
+     */
+    subscribed: boolean;
+    created_at_ms: number;
+    updated_at_ms: number;
+}
+interface PushSubscriptionPlaybookParams {
+    username: string;
+    name: string;
+}
+interface PushSubscriptionListParams {
+    /** Default `false`. When `true`, include rows with `subscribed=false`. */
+    include_history?: boolean;
+}
+interface PushSubscriptionListResponse {
+    items: PushSubscription[];
+}
+interface SubscribePushTargetResponse {
+    subscription: PushSubscription;
+    /** Canonical alfs path: `/alva/home/<username>/playbooks/<name>`. */
+    playbook_path: string;
+}
+interface UnsubscribePushTargetResponse {
+    ok: true;
+}
 
 declare class FsResource {
     private client;
@@ -456,6 +562,30 @@ declare class SdkDocsResource {
     }): Promise<PartitionSummaryResponse>;
 }
 
+interface SkillSummary {
+    name: string;
+    description: string;
+}
+interface SkillDoc {
+    name: string;
+    description: string;
+    content: string;
+}
+declare class SkillsResource {
+    private client;
+    constructor(client: AlvaClient);
+    list(): Promise<{
+        skills: SkillSummary[];
+    }>;
+    summary(params: {
+        name: string;
+    }): Promise<SkillDoc>;
+    endpoint(params: {
+        name: string;
+        file: string;
+    }): Promise<SkillDoc>;
+}
+
 declare class CommentsResource {
     private client;
     constructor(client: AlvaClient);
@@ -526,14 +656,79 @@ declare class TradingResource {
     updateRiskRules(rules: TradingRiskRuleInput): Promise<TradingRiskRule>;
 }
 
+declare class ArraysJwtResource {
+    private client;
+    constructor(client: AlvaClient);
+    /** Idempotently sign-or-renew the Arrays JWT server-side. */
+    ensure(): Promise<EnsureArraysJwtResponse>;
+    /** Report the current Arrays JWT state for the authenticated user. */
+    status(): Promise<ArraysJwtStatusResponse>;
+}
+
+declare class NotificationsResource {
+    private client;
+    constructor(client: AlvaClient);
+    /**
+     * List the caller's notification history for one playbook
+     * `(username, name)`. Returns `NOT_FOUND` when the playbook is
+     * private or does not exist (the two cases are deliberately
+     * indistinguishable to prevent namespace enumeration).
+     */
+    listPlaybook(params: NotificationListParams): Promise<PlaybookNotificationListResponse>;
+    /**
+     * List the caller's notification history for one feed
+     * `(username, name)`. Authorization is alfs read on
+     * `/alva/home/<username>/feeds/<name>`.
+     */
+    listFeed(params: NotificationListParams): Promise<FeedNotificationListResponse>;
+}
+
+/**
+ * Personal push subscriptions — opt the caller in or out of personal
+ * DM/web push for a target. Independent of social follow:
+ *
+ *   - `subscribePlaybook` does not start following.
+ *   - `unsubscribePlaybook` does not unfollow.
+ *   - Following a playbook elsewhere will compound-subscribe automatically.
+ *
+ * Backed by alva-gateway REST (mirrors the GraphQL surface in
+ * `pkg/schema/push_subscription.graphql`).
+ */
+declare class PushSubscriptionsResource {
+    private client;
+    constructor(client: AlvaClient);
+    /**
+     * Opt into personal push for one playbook `(username, name)`.
+     * Idempotent. Auth: callers must be able to read the playbook
+     * (public/paid pass; private requires explicit alfs grant).
+     */
+    subscribePlaybook(params: PushSubscriptionPlaybookParams): Promise<SubscribePushTargetResponse>;
+    /**
+     * Soft-disable personal push for one playbook `(username, name)`.
+     * Does NOT remove any social follow. Idempotent.
+     */
+    unsubscribePlaybook(params: PushSubscriptionPlaybookParams): Promise<UnsubscribePushTargetResponse>;
+    /**
+     * List the caller's personal push subscriptions across all targets.
+     * Defaults to currently-active rows only; pass `include_history=true`
+     * to also return previously-unsubscribed rows.
+     */
+    list(params?: PushSubscriptionListParams): Promise<PushSubscriptionListResponse>;
+}
+
 interface RequestOptions {
     query?: Record<string, unknown>;
     body?: unknown;
     /** Send raw body with application/octet-stream content type (for binary writes). */
     rawBody?: BodyInit;
+    /** Override the base URL for this request (e.g. the Arrays data-tools endpoint). */
+    baseUrl?: string;
+    /** If true, skip attaching any Alva auth header (X-Alva-Api-Key / x-Playbook-Viewer). */
+    noAuth?: boolean;
 }
 declare class AlvaClient {
     readonly baseUrl: string;
+    readonly arraysBaseUrl: string;
     readonly viewer_token?: string;
     readonly apiKey?: string;
     private _fs?;
@@ -542,11 +737,15 @@ declare class AlvaClient {
     private _release?;
     private _secrets?;
     private _sdk?;
+    private _skills?;
     private _comments?;
     private _remix?;
     private _screenshot?;
     private _user?;
     private _trading?;
+    private _arraysJwt?;
+    private _notifications?;
+    private _pushSubscriptions?;
     constructor(config: AlvaClientConfig);
     get fs(): FsResource;
     get run(): RunResource;
@@ -554,11 +753,15 @@ declare class AlvaClient {
     get release(): ReleaseResource;
     get secrets(): SecretsResource;
     get sdk(): SdkDocsResource;
+    get skills(): SkillsResource;
     get comments(): CommentsResource;
     get remix(): RemixResource;
     get screenshot(): ScreenshotResource;
     get user(): UserResource;
     get trading(): TradingResource;
+    get arraysJwt(): ArraysJwtResource;
+    get notifications(): NotificationsResource;
+    get pushSubscriptions(): PushSubscriptionsResource;
     _requireAuth(): void;
     _request(method: string, path: string, options?: RequestOptions): Promise<unknown>;
 }