@quantbrasil/cli 0.1.0-beta.0 → 0.1.0-beta.10

package/dist/vendor/core/capabilities/portfolios.js

@@ -1,13 +1,59 @@
 import { publicRuntimeVisibility, standardOutputModes } from "./shared.js";
+const portfolioIdPositional = {
+    kind: "positional",
+    name: "portfolio_id",
+    type: "integer",
+    required: true,
+    placeholder: "ID",
+    description: "Stable saved object identifier.",
+};
+const namePositional = {
+    kind: "positional",
+    name: "name",
+    type: "string",
+    required: true,
+    placeholder: "NOME",
+    description: "Name to save.",
+};
+const symbolsPositional = {
+    kind: "positional",
+    name: "symbols",
+    type: "string_array",
+    required: true,
+    placeholder: "TICKER",
+    multiple: true,
+    collectionFormat: "space_separated",
+    description: "One or more monitored ticker symbols.",
+};
+const targetsPositional = {
+    kind: "positional",
+    name: "targets",
+    type: "string_array",
+    required: true,
+    placeholder: "TICKER:PESO",
+    multiple: true,
+    collectionFormat: "space_separated",
+    description: "One or more target weights in TICKER:WEIGHT_PCT form.",
+};
+const positionsPositional = {
+    kind: "positional",
+    name: "positions",
+    type: "string_array",
+    required: true,
+    placeholder: "TICKER:QUANTIDADE",
+    multiple: true,
+    collectionFormat: "space_separated",
+    description: "One or more position quantities in TICKER:QUANTITY form.",
+};
 export const portfolioCapabilities = [
     {
-        id: "portfolios.list",
+        id: "watchlists.list",
         kind: "read",
         visibility: publicRuntimeVisibility,
-        description: "List every portfolio owned by the authenticated user.",
+        description: "List watchlists owned by the authenticated user.",
         http: {
             method: "GET",
-            path: "/api/desk/tools/portfolio/list",
+            path: "/api/desk/tools/watchlist/list",
             inputMode: "none",
             schemas: {
                 request: null,
@@ -15,27 +61,27 @@ export const portfolioCapabilities = [
             },
         },
         cli: {
-            group: "portfolios",
+            group: "watchlists",
             command: "list",
-            summary: "List the user portfolios available in QuantBrasil.",
+            summary: "List watchlists for tracking ideas and filters.",
             positional: [],
             options: [],
-            examples: ["quantbrasil portfolios list"],
+            examples: ["quantbrasil watchlists list"],
         },
         tool: {
-            name: "qb_portfolio_list",
-            title: "List portfolios",
+            name: "qb_watchlist_list",
+            title: "List watchlists",
         },
         outputModes: standardOutputModes,
     },
     {
-        id: "portfolios.get",
+        id: "watchlists.get",
         kind: "read",
         visibility: publicRuntimeVisibility,
-        description: "Return one saved portfolio by id, scoped to the acting user.",
+        description: "Return one watchlist by id, scoped to the acting user.",
         http: {
             method: "POST",
-            path: "/api/desk/tools/portfolio/get",
+            path: "/api/desk/tools/watchlist/get",
             inputMode: "json_body",
             schemas: {
                 request: "PortfolioGetRequest",
@@ -43,36 +89,27 @@ export const portfolioCapabilities = [
             },
         },
         cli: {
-            group: "portfolios",
+            group: "watchlists",
             command: "get",
-            summary: "Get a saved portfolio by id.",
-            positional: [
-                {
-                    kind: "positional",
-                    name: "portfolio_id",
-                    type: "integer",
-                    required: true,
-                    placeholder: "ID",
-                    description: "Saved portfolio identifier.",
-                },
-            ],
+            summary: "Get a watchlist by id.",
+            positional: [portfolioIdPositional],
             options: [],
-            examples: ["quantbrasil portfolios get 123"],
+            examples: ["quantbrasil watchlists get 123"],
         },
         tool: {
-            name: "qb_portfolio_get",
-            title: "Get portfolio",
+            name: "qb_watchlist_get",
+            title: "Get watchlist",
         },
         outputModes: standardOutputModes,
     },
     {
-        id: "portfolios.create",
+        id: "watchlists.create",
         kind: "mutation",
         visibility: publicRuntimeVisibility,
-        description: "Create a new saved portfolio for the authenticated user.",
+        description: "Create a new watchlist for the authenticated user.",
         http: {
             method: "POST",
-            path: "/api/desk/tools/portfolio/create",
+            path: "/api/desk/tools/watchlist/create",
             inputMode: "json_body",
             schemas: {
                 request: "PortfolioCreateRequest",
@@ -80,36 +117,27 @@ export const portfolioCapabilities = [
             },
         },
         cli: {
-            group: "portfolios",
+            group: "watchlists",
             command: "create",
-            summary: "Create a new portfolio.",
-            positional: [
-                {
-                    kind: "positional",
-                    name: "name",
-                    type: "string",
-                    required: true,
-                    placeholder: "NOME",
-                    description: "Portfolio name to create.",
-                },
-            ],
+            summary: "Create a new watchlist.",
+            positional: [namePositional],
             options: [],
-            examples: ['quantbrasil portfolios create "Dividendos"'],
+            examples: ['quantbrasil watchlists create "Dividendos"'],
         },
         tool: {
-            name: "qb_portfolio_create",
-            title: "Create portfolio",
+            name: "qb_watchlist_create",
+            title: "Create watchlist",
         },
         outputModes: standardOutputModes,
     },
     {
-        id: "portfolios.rename",
+        id: "watchlists.rename",
         kind: "mutation",
         visibility: publicRuntimeVisibility,
-        description: "Rename a saved portfolio owned by the authenticated user.",
+        description: "Rename a watchlist owned by the authenticated user.",
         http: {
             method: "POST",
-            path: "/api/desk/tools/portfolio/rename",
+            path: "/api/desk/tools/watchlist/rename",
             inputMode: "json_body",
             schemas: {
                 request: "PortfolioRenameRequest",
@@ -117,44 +145,27 @@ export const portfolioCapabilities = [
             },
         },
         cli: {
-            group: "portfolios",
+            group: "watchlists",
             command: "rename",
-            summary: "Rename an existing portfolio.",
-            positional: [
-                {
-                    kind: "positional",
-                    name: "portfolio_id",
-                    type: "integer",
-                    required: true,
-                    placeholder: "ID",
-                    description: "Saved portfolio identifier.",
-                },
-                {
-                    kind: "positional",
-                    name: "name",
-                    type: "string",
-                    required: true,
-                    placeholder: "NOME",
-                    description: "New portfolio name.",
-                },
-            ],
+            summary: "Rename an existing watchlist.",
+            positional: [portfolioIdPositional, namePositional],
             options: [],
-            examples: ['quantbrasil portfolios rename 123 "Longo Prazo"'],
+            examples: ['quantbrasil watchlists rename 123 "Longo Prazo"'],
         },
         tool: {
-            name: "qb_portfolio_rename",
-            title: "Rename portfolio",
+            name: "qb_watchlist_rename",
+            title: "Rename watchlist",
         },
         outputModes: standardOutputModes,
     },
     {
-        id: "portfolios.add-assets",
+        id: "watchlists.add-assets",
         kind: "mutation",
         visibility: publicRuntimeVisibility,
-        description: "Add one or more monitored tickers to a saved portfolio.",
+        description: "Add one or more monitored tickers to a watchlist.",
         http: {
             method: "POST",
-            path: "/api/desk/tools/portfolio/add_assets",
+            path: "/api/desk/tools/watchlist/add_assets",
             inputMode: "json_body",
             schemas: {
                 request: "PortfolioAddAssetsRequest",
@@ -162,82 +173,389 @@ export const portfolioCapabilities = [
             },
         },
         cli: {
-            group: "portfolios",
+            group: "watchlists",
             command: "add-assets",
-            summary: "Add monitored tickers to an existing portfolio.",
-            positional: [
+            summary: "Add monitored tickers to an existing watchlist.",
+            positional: [portfolioIdPositional, symbolsPositional],
+            options: [],
+            examples: ["quantbrasil watchlists add-assets 123 PETR4 VALE3"],
+        },
+        tool: {
+            name: "qb_watchlist_add_assets",
+            title: "Add watchlist assets",
+        },
+        outputModes: standardOutputModes,
+    },
+    {
+        id: "watchlists.remove-assets",
+        kind: "mutation",
+        visibility: publicRuntimeVisibility,
+        description: "Remove one or more monitored tickers from a watchlist.",
+        http: {
+            method: "POST",
+            path: "/api/desk/tools/watchlist/remove_assets",
+            inputMode: "json_body",
+            schemas: {
+                request: "PortfolioRemoveAssetsRequest",
+                response: "PortfolioMutationResponse",
+            },
+        },
+        cli: {
+            group: "watchlists",
+            command: "remove-assets",
+            summary: "Remove monitored tickers from an existing watchlist.",
+            positional: [portfolioIdPositional, symbolsPositional],
+            options: [],
+            examples: ["quantbrasil watchlists remove-assets 123 PETR4"],
+        },
+        tool: {
+            name: "qb_watchlist_remove_assets",
+            title: "Remove watchlist assets",
+        },
+        outputModes: standardOutputModes,
+    },
+    {
+        id: "holdings.list",
+        kind: "read",
+        visibility: publicRuntimeVisibility,
+        description: "List holdings owned by the authenticated user.",
+        http: {
+            method: "GET",
+            path: "/api/desk/tools/holding/list",
+            inputMode: "none",
+            schemas: {
+                request: null,
+                response: "PortfolioListResponse",
+            },
+        },
+        cli: {
+            group: "holdings",
+            command: "list",
+            summary: "List holdings for investable metrics.",
+            positional: [],
+            options: [],
+            examples: ["quantbrasil holdings list"],
+        },
+        tool: {
+            name: "qb_holding_list",
+            title: "List holdings",
+        },
+        outputModes: standardOutputModes,
+    },
+    {
+        id: "holdings.get",
+        kind: "read",
+        visibility: publicRuntimeVisibility,
+        description: "Return one holding by id, scoped to the acting user.",
+        http: {
+            method: "POST",
+            path: "/api/desk/tools/holding/get",
+            inputMode: "json_body",
+            schemas: {
+                request: "PortfolioGetRequest",
+                response: "PortfolioGetResponse",
+            },
+        },
+        cli: {
+            group: "holdings",
+            command: "get",
+            summary: "Get a holding by id.",
+            positional: [portfolioIdPositional],
+            options: [],
+            examples: ["quantbrasil holdings get 123"],
+        },
+        tool: {
+            name: "qb_holding_get",
+            title: "Get holding",
+        },
+        outputModes: standardOutputModes,
+    },
+    {
+        id: "holdings.create",
+        kind: "mutation",
+        visibility: publicRuntimeVisibility,
+        description: "Create a new holding for the authenticated user.",
+        http: {
+            method: "POST",
+            path: "/api/desk/tools/holding/create",
+            inputMode: "json_body",
+            schemas: {
+                request: "DeskHoldingCreateRequest",
+                response: "PortfolioCreateResponse",
+            },
+        },
+        cli: {
+            group: "holdings",
+            command: "create",
+            summary: "Create a new holding.",
+            positional: [namePositional],
+            options: [
                 {
-                    kind: "positional",
-                    name: "portfolio_id",
-                    type: "integer",
-                    required: true,
-                    placeholder: "ID",
-                    description: "Saved portfolio identifier.",
+                    kind: "option",
+                    flag: "--mode",
+                    name: "default_allocation_input",
+                    type: "enum",
+                    required: false,
+                    placeholder: "target|position",
+                    defaultValue: "target",
+                    enumValues: ["target", "position"],
+                    description: "How the holding is controlled initially: target weights or positions.",
                 },
                 {
-                    kind: "positional",
-                    name: "symbols",
+                    kind: "option",
+                    flag: "--target",
+                    name: "targets",
                     type: "string_array",
-                    required: true,
-                    placeholder: "TICKER",
+                    required: false,
+                    placeholder: "TICKER:PESO",
                     multiple: true,
-                    collectionFormat: "space_separated",
-                    description: "One or more monitored ticker symbols to add to the portfolio.",
+                    collectionFormat: "repeatable",
+                    description: "Initial target weight in TICKER:WEIGHT_PCT form.",
                 },
             ],
+            examples: [
+                'quantbrasil holdings create "Longo Prazo"',
+                'quantbrasil holdings create "Teórica" --target PRIO3:50 --target VALE3:50',
+                'quantbrasil holdings create "Real" --mode position',
+            ],
+        },
+        tool: {
+            name: "qb_holding_create",
+            title: "Create holding",
+        },
+        outputModes: standardOutputModes,
+    },
+    {
+        id: "holdings.rename",
+        kind: "mutation",
+        visibility: publicRuntimeVisibility,
+        description: "Rename a holding owned by the authenticated user.",
+        http: {
+            method: "POST",
+            path: "/api/desk/tools/holding/rename",
+            inputMode: "json_body",
+            schemas: {
+                request: "PortfolioRenameRequest",
+                response: "PortfolioMutationResponse",
+            },
+        },
+        cli: {
+            group: "holdings",
+            command: "rename",
+            summary: "Rename an existing holding.",
+            positional: [portfolioIdPositional, namePositional],
             options: [],
-            examples: ["quantbrasil portfolios add-assets 123 PETR4 VALE3"],
+            examples: ['quantbrasil holdings rename 123 "Longo Prazo"'],
         },
         tool: {
-            name: "qb_portfolio_add_assets",
-            title: "Add portfolio assets",
+            name: "qb_holding_rename",
+            title: "Rename holding",
         },
         outputModes: standardOutputModes,
     },
     {
-        id: "portfolios.remove-assets",
+        id: "holdings.set-targets",
         kind: "mutation",
         visibility: publicRuntimeVisibility,
-        description: "Remove one or more monitored tickers from a saved portfolio.",
+        description: "Set target weights for a holding owned by the authenticated user.",
         http: {
             method: "POST",
-            path: "/api/desk/tools/portfolio/remove_assets",
+            path: "/api/desk/tools/holding/set_targets",
             inputMode: "json_body",
             schemas: {
-                request: "PortfolioRemoveAssetsRequest",
+                request: "HoldingSetTargetsRequest",
                 response: "PortfolioMutationResponse",
             },
         },
         cli: {
-            group: "portfolios",
-            command: "remove-assets",
-            summary: "Remove monitored tickers from an existing portfolio.",
-            positional: [
+            group: "holdings",
+            command: "set-targets",
+            summary: "Set target weights for a holding.",
+            positional: [portfolioIdPositional, targetsPositional],
+            options: [],
+            examples: ["quantbrasil holdings set-targets 123 PRIO3:50 VALE3:50"],
+        },
+        tool: {
+            name: "qb_holding_set_targets",
+            title: "Set holding target weights",
+        },
+        outputModes: standardOutputModes,
+    },
+    {
+        id: "holdings.set-positions",
+        kind: "mutation",
+        visibility: publicRuntimeVisibility,
+        description: "Set position quantities for a holding owned by the authenticated user.",
+        http: {
+            method: "POST",
+            path: "/api/desk/tools/holding/set_positions",
+            inputMode: "json_body",
+            schemas: {
+                request: "HoldingSetPositionsRequest",
+                response: "PortfolioMutationResponse",
+            },
+        },
+        cli: {
+            group: "holdings",
+            command: "set-positions",
+            summary: "Set position quantities for a holding.",
+            positional: [portfolioIdPositional, positionsPositional],
+            options: [],
+            examples: [
+                "quantbrasil holdings set-positions 123 PRIO3:1600 BTC-USD:0.25",
+            ],
+        },
+        tool: {
+            name: "qb_holding_set_positions",
+            title: "Set holding position quantities",
+        },
+        outputModes: standardOutputModes,
+    },
+    {
+        id: "holdings.historical-return",
+        kind: "read",
+        visibility: publicRuntimeVisibility,
+        description: "Calculate historical return for a holding.",
+        http: {
+            method: "POST",
+            path: "/api/desk/tools/holding/historical_return",
+            inputMode: "json_body",
+            schemas: {
+                request: "PortfolioHistoricalReturnRequest",
+                response: "HistoricalReturnResponse",
+            },
+        },
+        cli: {
+            group: "holdings",
+            command: "historical-return",
+            summary: "Calculate historical return for a saved holding.",
+            positional: [portfolioIdPositional],
+            options: [
+                {
+                    kind: "option",
+                    flag: "--from",
+                    name: "start_date",
+                    type: "string",
+                    required: false,
+                    placeholder: "AAAA-MM-DD",
+                    description: "Inclusive start date in ISO format. Use with --to, or use --period.",
+                },
+                {
+                    kind: "option",
+                    flag: "--to",
+                    name: "end_date",
+                    type: "string",
+                    required: false,
+                    placeholder: "AAAA-MM-DD",
+                    description: "Inclusive end date in ISO format. Use with --from, or use --period.",
+                },
+                {
+                    kind: "option",
+                    flag: "--period",
+                    name: "period",
+                    type: "string",
+                    required: false,
+                    placeholder: "PERIODO",
+                    description: "Lookback period such as 1y, 3y, 5y, or 6m. Mutually exclusive with --from/--to.",
+                },
+            ],
+            examples: [
+                "quantbrasil holdings historical-return 123 --from 2024-01-01 --to 2025-01-01",
+                "quantbrasil holdings historical-return 123 --period 1y",
+            ],
+        },
+        tool: {
+            name: "qb_holding_historical_return",
+            title: "Calculate holding historical return",
+        },
+        outputModes: standardOutputModes,
+    },
+    {
+        id: "holdings.beta",
+        kind: "read",
+        visibility: publicRuntimeVisibility,
+        description: "Calculate holding beta against IBOV.",
+        http: {
+            method: "POST",
+            path: "/api/desk/tools/holding/beta",
+            inputMode: "json_body",
+            schemas: {
+                request: "PortfolioBetaRequest",
+                response: "PortfolioBetaResponse",
+            },
+        },
+        cli: {
+            group: "holdings",
+            command: "beta",
+            summary: "Calculate holding beta against IBOV.",
+            positional: [portfolioIdPositional],
+            options: [
+                {
+                    kind: "option",
+                    flag: "--years",
+                    name: "years",
+                    type: "enum",
+                    required: false,
+                    placeholder: "ANOS",
+                    defaultValue: 1,
+                    enumValues: ["1", "3", "5"],
+                    description: "Historical lookback window in years. Accepted values: 1, 3, or 5.",
+                },
+            ],
+            examples: ["quantbrasil holdings beta 123 --years 3"],
+        },
+        tool: {
+            name: "qb_holding_beta",
+            title: "Calculate holding beta",
+        },
+        outputModes: standardOutputModes,
+    },
+    {
+        id: "holdings.var",
+        kind: "read",
+        visibility: publicRuntimeVisibility,
+        description: "Calculate one-day Value-at-Risk for a holding.",
+        http: {
+            method: "POST",
+            path: "/api/desk/tools/holding/var",
+            inputMode: "json_body",
+            schemas: {
+                request: "PortfolioVaRRequest",
+                response: "PortfolioVaRResponse",
+            },
+        },
+        cli: {
+            group: "holdings",
+            command: "var",
+            summary: "Calculate one-day Value-at-Risk for a holding.",
+            positional: [portfolioIdPositional],
+            options: [
                 {
-                    kind: "positional",
-                    name: "portfolio_id",
+                    kind: "option",
+                    flag: "--years",
+                    name: "years",
                     type: "integer",
-                    required: true,
-                    placeholder: "ID",
-                    description: "Saved portfolio identifier.",
+                    required: false,
+                    placeholder: "ANOS",
+                    defaultValue: 1,
+                    description: "Historical lookback window in years. The VaR horizon remains one day.",
                 },
                 {
-                    kind: "positional",
-                    name: "symbols",
-                    type: "string_array",
-                    required: true,
-                    placeholder: "TICKER",
-                    multiple: true,
-                    collectionFormat: "space_separated",
-                    description: "One or more monitored ticker symbols to remove from the portfolio.",
+                    kind: "option",
+                    flag: "--confidence",
+                    name: "confidence_pct",
+                    type: "number",
+                    required: false,
+                    placeholder: "PERCENTUAL",
+                    defaultValue: 95,
+                    description: "Confidence level in percent, for example 95 or 99.",
                 },
             ],
-            options: [],
-            examples: ["quantbrasil portfolios remove-assets 123 PETR4"],
+            examples: ["quantbrasil holdings var 123 --years 1 --confidence 95"],
         },
         tool: {
-            name: "qb_portfolio_remove_assets",
-            title: "Remove portfolio assets",
+            name: "qb_holding_var",
+            title: "Calculate holding VaR",
         },
         outputModes: standardOutputModes,
     },