@alva-ai/toolkit 0.7.0 → 0.8.0

package/dist/index.d.cts

@@ -209,6 +209,14 @@ interface FeedReleaseResponse {
     /** Canonical alfs path: `/alva/home/<username>/feeds/<name>`. */
     feed_path: string;
 }
+interface FeedDeleteRequest {
+    /** Numeric feed id to delete. */
+    id: number;
+}
+interface FeedDeleteResponse {
+    /** Echoed feed id (string form, matching gateway response). */
+    id: string;
+}
 interface PlaybookDraftRequest {
     name: string;
     display_name: string;
@@ -219,11 +227,20 @@ interface PlaybookDraftRequest {
     }>;
     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.
+     * Optional source-skill reference in "username/name" form (e.g.
+     * "alva/screener"). The value identifies a playbook skill published to
+     * Skillhub; discover available skills via `alva skillhub list`.
+     * Persisted set-once on the playbook's first draft; subsequent drafts
+     * ignore the field.
+     */
+    skill_id?: string;
+    /**
+     * Optional discovery tags (max 10, each up to 32 characters). On a
+     * playbook's first draft these merge with any template-inherited tags;
+     * on a re-draft of an existing playbook they replace the current tag
+     * set. Omitted/empty leaves tags unchanged.
      */
-    template_id?: string;
+    tags?: string[];
 }
 interface PlaybookDraftResponse {
     playbook_id: number;
@@ -470,15 +487,25 @@ interface PushTarget {
 }
 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;
+    /** Present on list responses. */
+    cursor?: string;
+    /** Feed metadata is present for FEED targets when available. */
+    feed_name?: string;
+    feed_status?: 'ACTIVE' | 'PAUSED' | 'UNSPECIFIED' | string;
+    /** Unix milliseconds of the latest successful delivery for this user+target. */
+    last_pushed_at_ms?: number;
+    /** Playbooks whose latest release currently references this feed. */
+    used_by?: PushSubscriptionUsedBy[];
+    used_by_total?: number;
+}
+interface PushSubscriptionUsedBy {
+    playbook_id: string;
+    owner_username: string;
+    playbook_name: string;
+    display_name: string;
+    owner_avatar_url: string;
 }
 interface PushSubscriptionPlaybookParams {
     username: string;
@@ -489,11 +516,15 @@ interface PushSubscriptionFeedParams {
     name: string;
 }
 interface PushSubscriptionListParams {
-    /** Default `false`. When `true`, include rows with `subscribed=false`. */
-    include_history?: boolean;
+    /** Page size, default 50, max 200 server-side. */
+    first?: number;
+    /** Opaque cursor token from previous page's `next_cursor`. */
+    cursor?: string;
 }
 interface PushSubscriptionListResponse {
     items: PushSubscription[];
+    /** Empty when there is no next page. */
+    next_cursor?: string;
 }
 interface SubscribePushTargetResponse {
     subscription: PushSubscription;
@@ -636,6 +667,24 @@ declare class ReleaseResource {
     playbook(params: PlaybookReleaseRequest): Promise<PlaybookReleaseResponse>;
 }
 
+/**
+ * Feed lifecycle management. Backed by alva-gateway REST (mirrors the
+ * GraphQL surface in `pkg/schema/feed.graphql`).
+ */
+declare class FeedResource {
+    private client;
+    constructor(client: AlvaClient);
+    /**
+     * Soft-delete a feed and all its active majors. Cascades:
+     *   - all active feed_majors are soft-deleted in the same transaction
+     *   - associated producer cronjobs are removed best-effort (the cronjob
+     *     scavenger reconciles any leftover rows on its next sweep)
+     *
+     * Auth: caller must own the feed (uid match), enforced by the backend.
+     */
+    delete(params: FeedDeleteRequest): Promise<FeedDeleteResponse>;
+}
+
 declare class SecretsResource {
     private client;
     constructor(client: AlvaClient);
@@ -859,7 +908,8 @@ declare class NotificationsResource {
  *
  *   - `subscribePlaybook` / `subscribeFeed` do not start following.
  *   - `unsubscribePlaybook` / `unsubscribeFeed` do not unfollow.
- *   - Following a playbook elsewhere will compound-subscribe automatically.
+ *   - Following a playbook elsewhere does not create or revive a push
+ *     subscription.
  *
  * Backed by alva-gateway REST (mirrors the GraphQL surface in
  * `pkg/schema/push_subscription.graphql`).
@@ -892,9 +942,8 @@ declare class PushSubscriptionsResource {
      */
     unsubscribeFeed(params: PushSubscriptionFeedParams): Promise<UnsubscribePushTargetResponse>;
     /**
-     * List the caller's personal push subscriptions across all targets
-     * (playbook + feed). Defaults to currently-active rows only; pass
-     * `include_history=true` to also return previously-unsubscribed rows.
+     * List the caller's currently active personal push subscriptions.
+     * Results are cursor-paginated.
      */
     list(params?: PushSubscriptionListParams): Promise<PushSubscriptionListResponse>;
 }
@@ -936,6 +985,7 @@ declare class AlvaClient {
     private _run?;
     private _deploy?;
     private _release?;
+    private _feed?;
     private _secrets?;
     private _sdk?;
     private _dataSkills?;
@@ -954,6 +1004,7 @@ declare class AlvaClient {
     get run(): RunResource;
     get deploy(): DeployResource;
     get release(): ReleaseResource;
+    get feed(): FeedResource;
     get secrets(): SecretsResource;
     get sdk(): SdkDocsResource;
     get dataSkills(): DataSkillsResource;
@@ -980,4 +1031,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, type SkillDoc, type SkillEndpointMetadata, type SkillEndpointTier, type SkillMetadata, type SkillSummary, 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 FeedDeleteRequest, type FeedDeleteResponse, 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

@@ -209,6 +209,14 @@ interface FeedReleaseResponse {
     /** Canonical alfs path: `/alva/home/<username>/feeds/<name>`. */
     feed_path: string;
 }
+interface FeedDeleteRequest {
+    /** Numeric feed id to delete. */
+    id: number;
+}
+interface FeedDeleteResponse {
+    /** Echoed feed id (string form, matching gateway response). */
+    id: string;
+}
 interface PlaybookDraftRequest {
     name: string;
     display_name: string;
@@ -219,11 +227,20 @@ interface PlaybookDraftRequest {
     }>;
     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.
+     * Optional source-skill reference in "username/name" form (e.g.
+     * "alva/screener"). The value identifies a playbook skill published to
+     * Skillhub; discover available skills via `alva skillhub list`.
+     * Persisted set-once on the playbook's first draft; subsequent drafts
+     * ignore the field.
+     */
+    skill_id?: string;
+    /**
+     * Optional discovery tags (max 10, each up to 32 characters). On a
+     * playbook's first draft these merge with any template-inherited tags;
+     * on a re-draft of an existing playbook they replace the current tag
+     * set. Omitted/empty leaves tags unchanged.
      */
-    template_id?: string;
+    tags?: string[];
 }
 interface PlaybookDraftResponse {
     playbook_id: number;
@@ -470,15 +487,25 @@ interface PushTarget {
 }
 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;
+    /** Present on list responses. */
+    cursor?: string;
+    /** Feed metadata is present for FEED targets when available. */
+    feed_name?: string;
+    feed_status?: 'ACTIVE' | 'PAUSED' | 'UNSPECIFIED' | string;
+    /** Unix milliseconds of the latest successful delivery for this user+target. */
+    last_pushed_at_ms?: number;
+    /** Playbooks whose latest release currently references this feed. */
+    used_by?: PushSubscriptionUsedBy[];
+    used_by_total?: number;
+}
+interface PushSubscriptionUsedBy {
+    playbook_id: string;
+    owner_username: string;
+    playbook_name: string;
+    display_name: string;
+    owner_avatar_url: string;
 }
 interface PushSubscriptionPlaybookParams {
     username: string;
@@ -489,11 +516,15 @@ interface PushSubscriptionFeedParams {
     name: string;
 }
 interface PushSubscriptionListParams {
-    /** Default `false`. When `true`, include rows with `subscribed=false`. */
-    include_history?: boolean;
+    /** Page size, default 50, max 200 server-side. */
+    first?: number;
+    /** Opaque cursor token from previous page's `next_cursor`. */
+    cursor?: string;
 }
 interface PushSubscriptionListResponse {
     items: PushSubscription[];
+    /** Empty when there is no next page. */
+    next_cursor?: string;
 }
 interface SubscribePushTargetResponse {
     subscription: PushSubscription;
@@ -636,6 +667,24 @@ declare class ReleaseResource {
     playbook(params: PlaybookReleaseRequest): Promise<PlaybookReleaseResponse>;
 }
 
+/**
+ * Feed lifecycle management. Backed by alva-gateway REST (mirrors the
+ * GraphQL surface in `pkg/schema/feed.graphql`).
+ */
+declare class FeedResource {
+    private client;
+    constructor(client: AlvaClient);
+    /**
+     * Soft-delete a feed and all its active majors. Cascades:
+     *   - all active feed_majors are soft-deleted in the same transaction
+     *   - associated producer cronjobs are removed best-effort (the cronjob
+     *     scavenger reconciles any leftover rows on its next sweep)
+     *
+     * Auth: caller must own the feed (uid match), enforced by the backend.
+     */
+    delete(params: FeedDeleteRequest): Promise<FeedDeleteResponse>;
+}
+
 declare class SecretsResource {
     private client;
     constructor(client: AlvaClient);
@@ -859,7 +908,8 @@ declare class NotificationsResource {
  *
  *   - `subscribePlaybook` / `subscribeFeed` do not start following.
  *   - `unsubscribePlaybook` / `unsubscribeFeed` do not unfollow.
- *   - Following a playbook elsewhere will compound-subscribe automatically.
+ *   - Following a playbook elsewhere does not create or revive a push
+ *     subscription.
  *
  * Backed by alva-gateway REST (mirrors the GraphQL surface in
  * `pkg/schema/push_subscription.graphql`).
@@ -892,9 +942,8 @@ declare class PushSubscriptionsResource {
      */
     unsubscribeFeed(params: PushSubscriptionFeedParams): Promise<UnsubscribePushTargetResponse>;
     /**
-     * List the caller's personal push subscriptions across all targets
-     * (playbook + feed). Defaults to currently-active rows only; pass
-     * `include_history=true` to also return previously-unsubscribed rows.
+     * List the caller's currently active personal push subscriptions.
+     * Results are cursor-paginated.
      */
     list(params?: PushSubscriptionListParams): Promise<PushSubscriptionListResponse>;
 }
@@ -936,6 +985,7 @@ declare class AlvaClient {
     private _run?;
     private _deploy?;
     private _release?;
+    private _feed?;
     private _secrets?;
     private _sdk?;
     private _dataSkills?;
@@ -954,6 +1004,7 @@ declare class AlvaClient {
     get run(): RunResource;
     get deploy(): DeployResource;
     get release(): ReleaseResource;
+    get feed(): FeedResource;
     get secrets(): SecretsResource;
     get sdk(): SdkDocsResource;
     get dataSkills(): DataSkillsResource;
@@ -980,4 +1031,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, type SkillDoc, type SkillEndpointMetadata, type SkillEndpointTier, type SkillMetadata, type SkillSummary, 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 FeedDeleteRequest, type FeedDeleteResponse, 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.js

@@ -275,7 +275,8 @@ var ReleaseResource = class {
         description: params.description,
         feeds: params.feeds,
         trading_symbols: params.trading_symbols,
-        template_id: params.template_id
+        skill_id: params.skill_id,
+        tags: params.tags
       }
     });
   }
@@ -293,6 +294,32 @@ var ReleaseResource = class {
   }
 };
 
+// src/resources/feed.ts
+var FeedResource = class {
+  constructor(client) {
+    this.client = client;
+  }
+  client;
+  /**
+   * Soft-delete a feed and all its active majors. Cascades:
+   *   - all active feed_majors are soft-deleted in the same transaction
+   *   - associated producer cronjobs are removed best-effort (the cronjob
+   *     scavenger reconciles any leftover rows on its next sweep)
+   *
+   * Auth: caller must own the feed (uid match), enforced by the backend.
+   */
+  async delete(params) {
+    this.client._requireAuth();
+    if (!Number.isInteger(params.id) || params.id <= 0) {
+      throw new Error("feed id must be a positive integer");
+    }
+    return this.client._request(
+      "DELETE",
+      `/api/v1/feed/${encodeURIComponent(String(params.id))}`
+    );
+  }
+};
+
 // src/resources/secrets.ts
 var SecretsResource = class {
   constructor(client) {
@@ -1854,16 +1881,16 @@ var PushSubscriptionsResource = class {
     );
   }
   /**
-   * List the caller's personal push subscriptions across all targets
-   * (playbook + feed). Defaults to currently-active rows only; pass
-   * `include_history=true` to also return previously-unsubscribed rows.
+   * List the caller's currently active personal push subscriptions.
+   * Results are cursor-paginated.
    */
   async list(params = {}) {
     this.client._requireAuth();
     const query = {};
-    if (params.include_history !== void 0) {
-      query.include_history = String(params.include_history);
+    if (params.first !== void 0 && params.first > 0) {
+      query.first = String(params.first);
     }
+    if (params.cursor) query.cursor = params.cursor;
     return this.client._request("GET", "/api/v1/me/push-subscriptions", {
       query
     });
@@ -1945,6 +1972,7 @@ var AlvaClient = class {
   _run;
   _deploy;
   _release;
+  _feed;
   _secrets;
   _sdk;
   _dataSkills;
@@ -1976,6 +2004,9 @@ var AlvaClient = class {
   get release() {
     return this._release ??= new ReleaseResource(this);
   }
+  get feed() {
+    return this._feed ??= new FeedResource(this);
+  }
   get secrets() {
     return this._secrets ??= new SecretsResource(this);
   }
@@ -2107,7 +2138,7 @@ var AlvaClient = class {
 };
 
 // src/index.ts
-var VERSION = true ? "0.7.0" : "dev";
+var VERSION = true ? "0.8.0" : "dev";
 export {
   AlvaClient,
   AlvaError,