@pikku/addon-graph 0.0.2 → 0.12.0

package/.pikku/console/pikku-addon-meta.gen.json

@@ -0,0 +1,281 @@
+{
+  "nodes": {
+    "aggregate": {
+      "name": "aggregate",
+      "displayName": "Aggregate",
+      "category": "Array",
+      "type": "action",
+      "rpc": "aggregate",
+      "description": "Combine a field from many items into a list in a single item",
+      "errorOutput": false,
+      "inputSchemaName": "AggregateInput",
+      "outputSchemaName": "AggregateOutput"
+    },
+    "chunk": {
+      "name": "chunk",
+      "displayName": "Chunk",
+      "category": "Array",
+      "type": "action",
+      "rpc": "chunk",
+      "description": "Split array into chunks of specified size",
+      "errorOutput": false,
+      "inputSchemaName": "ChunkInput",
+      "outputSchemaName": "ChunkOutput"
+    },
+    "find": {
+      "name": "find",
+      "displayName": "Find",
+      "category": "Array",
+      "type": "action",
+      "rpc": "find",
+      "description": "Find the first item matching a field value",
+      "errorOutput": false,
+      "inputSchemaName": "FindInput",
+      "outputSchemaName": "FindOutput"
+    },
+    "groupBy": {
+      "name": "groupBy",
+      "displayName": "Group By",
+      "category": "Array",
+      "type": "action",
+      "rpc": "groupBy",
+      "description": "Group items by a field value",
+      "errorOutput": false,
+      "inputSchemaName": "GroupByInput",
+      "outputSchemaName": "GroupByOutput"
+    },
+    "limit": {
+      "name": "limit",
+      "displayName": "Limit",
+      "category": "Array",
+      "type": "action",
+      "rpc": "limit",
+      "description": "Restrict the number of items",
+      "errorOutput": false,
+      "inputSchemaName": "LimitInput",
+      "outputSchemaName": "LimitOutput"
+    },
+    "removeDuplicates": {
+      "name": "removeDuplicates",
+      "displayName": "Remove Duplicates",
+      "category": "Array",
+      "type": "action",
+      "rpc": "removeDuplicates",
+      "description": "Delete items with matching field values",
+      "errorOutput": false,
+      "inputSchemaName": "RemoveDuplicatesInput",
+      "outputSchemaName": "RemoveDuplicatesOutput"
+    },
+    "reverse": {
+      "name": "reverse",
+      "displayName": "Reverse",
+      "category": "Array",
+      "type": "action",
+      "rpc": "reverse",
+      "description": "Reverse the order of items in an array",
+      "errorOutput": false,
+      "inputSchemaName": "ReverseInput",
+      "outputSchemaName": "ReverseOutput"
+    },
+    "sort": {
+      "name": "sort",
+      "displayName": "Sort",
+      "category": "Array",
+      "type": "action",
+      "rpc": "sort",
+      "description": "Change items order",
+      "errorOutput": false,
+      "inputSchemaName": "SortInput",
+      "outputSchemaName": "SortOutput"
+    },
+    "splitOut": {
+      "name": "splitOut",
+      "displayName": "Split Out",
+      "category": "Array",
+      "type": "action",
+      "rpc": "splitOut",
+      "description": "Turn a list inside item(s) into separate items",
+      "errorOutput": false,
+      "inputSchemaName": "SplitOutInput",
+      "outputSchemaName": "SplitOutOutput"
+    },
+    "summarize": {
+      "name": "summarize",
+      "displayName": "Summarize",
+      "category": "Array",
+      "type": "action",
+      "rpc": "summarize",
+      "description": "Sum, count, max, etc. across items",
+      "errorOutput": false,
+      "inputSchemaName": "SummarizeInput",
+      "outputSchemaName": "SummarizeOutput"
+    },
+    "unique": {
+      "name": "unique",
+      "displayName": "Unique",
+      "category": "Array",
+      "type": "action",
+      "rpc": "unique",
+      "description": "Get unique values from an array",
+      "errorOutput": false,
+      "inputSchemaName": "UniqueInput",
+      "outputSchemaName": "UniqueOutput"
+    },
+    "coalesce": {
+      "name": "coalesce",
+      "displayName": "Coalesce",
+      "category": "Data",
+      "type": "action",
+      "rpc": "coalesce",
+      "description": "Return the first non-null value",
+      "errorOutput": false,
+      "inputSchemaName": "CoalesceInput",
+      "outputSchemaName": "CoalesceOutput"
+    },
+    "crypto": {
+      "name": "crypto",
+      "displayName": "Crypto",
+      "category": "Data",
+      "type": "action",
+      "rpc": "crypto",
+      "description": "Provide cryptographic utilities",
+      "errorOutput": false,
+      "inputSchemaName": "CryptoInput",
+      "outputSchemaName": "CryptoOutput"
+    },
+    "dateTime": {
+      "name": "dateTime",
+      "displayName": "Date & Time",
+      "category": "Data",
+      "type": "action",
+      "rpc": "dateTime",
+      "description": "Manipulate date and time values",
+      "errorOutput": false,
+      "inputSchemaName": "DateTimeInput",
+      "outputSchemaName": "DateTimeOutput"
+    },
+    "jwtSign": {
+      "name": "jwtSign",
+      "displayName": "JWT Sign",
+      "category": "Data",
+      "type": "action",
+      "rpc": "jwtSign",
+      "description": "Sign a payload into a JWT token",
+      "errorOutput": false,
+      "inputSchemaName": "JwtSignInput",
+      "outputSchemaName": "JwtSignOutput"
+    },
+    "jwtDecode": {
+      "name": "jwtDecode",
+      "displayName": "JWT Decode",
+      "category": "Data",
+      "type": "action",
+      "rpc": "jwtDecode",
+      "description": "Decode a JWT token into its payload",
+      "errorOutput": false,
+      "inputSchemaName": "JwtDecodeInput",
+      "outputSchemaName": "JwtDecodeOutput"
+    },
+    "math": {
+      "name": "math",
+      "displayName": "Math",
+      "category": "Data",
+      "type": "action",
+      "rpc": "math",
+      "description": "Perform math operations",
+      "errorOutput": false,
+      "inputSchemaName": "MathInput",
+      "outputSchemaName": "MathOutput"
+    },
+    "sleep": {
+      "name": "sleep",
+      "displayName": "Sleep",
+      "category": "Data",
+      "type": "action",
+      "rpc": "sleep",
+      "description": "Sleep for a specified duration before continuing",
+      "errorOutput": false,
+      "inputSchemaName": "SleepInput",
+      "outputSchemaName": null
+    },
+    "stringTransform": {
+      "name": "stringTransform",
+      "displayName": "String Transform",
+      "category": "Data",
+      "type": "action",
+      "rpc": "stringTransform",
+      "description": "Transform strings (case, trim, split, replace, etc.)",
+      "errorOutput": false,
+      "inputSchemaName": "StringTransformInput",
+      "outputSchemaName": "StringTransformOutput"
+    },
+    "typeConvert": {
+      "name": "typeConvert",
+      "displayName": "Type Convert",
+      "category": "Data",
+      "type": "action",
+      "rpc": "typeConvert",
+      "description": "Convert between types (string, number, boolean, json, array)",
+      "errorOutput": false,
+      "inputSchemaName": "TypeConvertInput",
+      "outputSchemaName": "TypeConvertOutput"
+    },
+    "editFields": {
+      "name": "editFields",
+      "displayName": "Edit Fields",
+      "category": "Transform",
+      "type": "action",
+      "rpc": "editFields",
+      "description": "Modify, add, or remove item fields",
+      "errorOutput": false,
+      "inputSchemaName": "EditFieldsInput",
+      "outputSchemaName": "EditFieldsOutput"
+    },
+    "merge": {
+      "name": "merge",
+      "displayName": "Merge",
+      "category": "Transform",
+      "type": "action",
+      "rpc": "merge",
+      "description": "Merge multiple objects into one",
+      "errorOutput": false,
+      "inputSchemaName": "MergeInput",
+      "outputSchemaName": "MergeOutput"
+    },
+    "omit": {
+      "name": "omit",
+      "displayName": "Omit",
+      "category": "Transform",
+      "type": "action",
+      "rpc": "omit",
+      "description": "Remove specified fields from an object",
+      "errorOutput": false,
+      "inputSchemaName": "OmitInput",
+      "outputSchemaName": "OmitOutput"
+    },
+    "pick": {
+      "name": "pick",
+      "displayName": "Pick",
+      "category": "Transform",
+      "type": "action",
+      "rpc": "pick",
+      "description": "Keep only specified fields from an object",
+      "errorOutput": false,
+      "inputSchemaName": "PickInput",
+      "outputSchemaName": "PickOutput"
+    },
+    "renameKeys": {
+      "name": "renameKeys",
+      "displayName": "Rename Keys",
+      "category": "Transform",
+      "type": "action",
+      "rpc": "renameKeys",
+      "description": "Update item field names",
+      "errorOutput": false,
+      "inputSchemaName": "RenameKeysInput",
+      "outputSchemaName": "RenameKeysOutput"
+    }
+  },
+  "secrets": {},
+  "package": {}
+}

package/.pikku/console/pikku-node-types.gen.ts

@@ -1,8 +1,8 @@
 /**
- * This file was generated by @pikku/cli@0.12.2
+ * This file was generated by @pikku/cli@0.12.19
  */
 import type { FlattenedRPCMap } from '../rpc/pikku-rpc-wirings-map.internal.gen.js'
 
-export type NodeCategory = 'Transform' | 'Array' | 'Data'
+export type NodeCategory = never
 
 export type NodeRPCName = keyof FlattenedRPCMap

package/.pikku/function/pikku-function-types.gen.ts

@@ -1,13 +1,16 @@
 /**
- * This file was generated by @pikku/cli@0.12.2
+ * This file was generated by @pikku/cli@0.12.19
  */
 /**
  * Core function, middleware, and permission types for all wirings
  */
 
-import { CorePikkuFunctionConfig, CorePikkuAuth, CorePikkuAuthConfig, CorePikkuPermission, CorePikkuMiddleware, CorePermissionGroup, addMiddleware as addMiddlewareCore, addPermission as addPermissionCore, PikkuWire, PickRequired } from '@pikku/core'
+import type { CorePikkuMiddleware, CorePermissionGroup, PikkuWire, PickRequired } from '@pikku/core'
+import type { CorePikkuFunctionConfig, CorePikkuAuth, CorePikkuAuthConfig, CorePikkuPermission } from '@pikku/core/function'
+import { pikkuAuth as pikkuAuthCore } from '@pikku/core/function'
+import { addMiddleware as addMiddlewareCore, addPermission as addPermissionCore } from '@pikku/core/middleware'
 import { pikkuState as __pikkuState, CreateWireServices } from '@pikku/core/internal'
-import { pikkuAuth as pikkuAuthCore } from '@pikku/core'
+import { PikkuError } from '@pikku/core/errors'
 import type { NodeType } from '@pikku/core/node'
 import type { StandardSchemaV1 } from '@standard-schema/spec'
 import { CorePikkuFunction, CorePikkuFunctionSessionless } from '@pikku/core/function'
@@ -30,7 +33,7 @@ export type Session = UserSession
  */
 export type NodeConfig = {
   displayName: string
-  category: 'Transform' | 'Array' | 'Data'
+  category: string
   type: NodeType
   errorOutput?: boolean
 }
@@ -222,6 +225,37 @@ export const pikkuPermissionFactory = <In = any>(
   return factory
 }
 
+/**
+ * A function that generates a human-readable description of a pending approval action.
+ * Used by AI agents to show meaningful approval prompts instead of raw tool arguments.
+ *
+ * @template In - The input type (same as the function it describes)
+ * @template RequiredServices - The services required for this description function
+ */
+export type PikkuApprovalDescription<In = unknown, RequiredServices extends Services = Services> = (
+  services: RequiredServices,
+  data: In
+) => Promise<string>
+
+/**
+ * Factory function for creating approval description functions with tree-shaking support.
+ *
+ * @example
+ * ```typescript
+ * export const deleteTodoApproval = pikkuApprovalDescription(
+ *   async ({ todoStore }, { id }) => {
+ *     const todo = await todoStore.get(id)
+ *     return \`Delete todo: "${todo.title}"\`
+ *   }
+ * )
+ * ```
+ */
+export const pikkuApprovalDescription = <In = unknown, RequiredServices extends Services = Services>(
+  fn: PikkuApprovalDescription<In, RequiredServices>
+): PikkuApprovalDescription<In, RequiredServices> => {
+  return fn
+}
+
 /**
  * A sessionless API function that doesn't require user authentication.
  * Use this for public endpoints, health checks, or operations that don't need user context.
@@ -292,7 +326,7 @@ export type PikkuFunctionConfig<
  * Types are automatically inferred from the schemas.
  */
 export type PikkuFunctionConfigWithSchema<
-  InputSchema extends StandardSchemaV1,
+  InputSchema extends StandardSchemaV1 | undefined = undefined,
   OutputSchema extends StandardSchemaV1 | undefined = undefined,
   RequiredWires extends keyof PikkuWire = never
 > = {
@@ -301,21 +335,24 @@ export type PikkuFunctionConfigWithSchema<
   expose?: boolean
   mcp?: boolean
   internal?: boolean
+  approvalRequired?: boolean
+  approvalDescription?: InputSchema extends StandardSchemaV1 ? PikkuApprovalDescription<InferSchemaOutput<InputSchema>> : never
   func: PikkuFunction<
-    InferSchemaOutput<InputSchema>,
+    InputSchema extends StandardSchemaV1 ? InferSchemaOutput<InputSchema> : unknown,
     OutputSchema extends StandardSchemaV1 ? InferSchemaOutput<OutputSchema> : unknown,
     RequiredWires
   > | PikkuFunctionSessionless<
-    InferSchemaOutput<InputSchema>,
+    InputSchema extends StandardSchemaV1 ? InferSchemaOutput<InputSchema> : unknown,
     OutputSchema extends StandardSchemaV1 ? InferSchemaOutput<OutputSchema> : unknown,
     RequiredWires
   >
   auth?: boolean
-  permissions?: CorePermissionGroup<PikkuPermission<InferSchemaOutput<InputSchema>>>
+  permissions?: InputSchema extends StandardSchemaV1 ? CorePermissionGroup<PikkuPermission<InferSchemaOutput<InputSchema>>> : undefined
   middleware?: PikkuMiddleware[]
-  input: InputSchema
+  input?: InputSchema
   output?: OutputSchema
   node?: NodeConfig
+  errors?: Array<typeof PikkuError>
 }
 
 /**
@@ -357,11 +394,11 @@ export type PikkuFunctionConfigWithSchema<
  * ```
  */
 export function pikkuFunc<
-  InputSchema extends StandardSchemaV1,
+  InputSchema extends StandardSchemaV1 | undefined = undefined,
   OutputSchema extends StandardSchemaV1 | undefined = undefined
 >(
   config: PikkuFunctionConfigWithSchema<InputSchema, OutputSchema, 'session' | 'rpc'>
-): PikkuFunctionConfig<InferSchemaOutput<InputSchema>, OutputSchema extends StandardSchemaV1 ? InferSchemaOutput<OutputSchema> : unknown, 'session' | 'rpc'>
+): PikkuFunctionConfig<InputSchema extends StandardSchemaV1 ? InferSchemaOutput<InputSchema> : unknown, OutputSchema extends StandardSchemaV1 ? InferSchemaOutput<OutputSchema> : unknown, 'session' | 'rpc'>
 export function pikkuFunc<In, Out = unknown>(
   func:
     | PikkuFunction<In, Out, 'session' | 'rpc'>
@@ -375,7 +412,7 @@ export function pikkuFunc(func: any) {
  * Configuration object for sessionless Pikku functions with Zod schema validation.
  */
 export type PikkuFunctionSessionlessConfigWithSchema<
-  InputSchema extends StandardSchemaV1,
+  InputSchema extends StandardSchemaV1 | undefined = undefined,
   OutputSchema extends StandardSchemaV1 | undefined = undefined,
   RequiredWires extends keyof PikkuWire = never
 > = {
@@ -386,17 +423,20 @@ export type PikkuFunctionSessionlessConfigWithSchema<
   mcp?: boolean
   internal?: boolean
   remote?: boolean
+  approvalRequired?: boolean
+  approvalDescription?: InputSchema extends StandardSchemaV1 ? PikkuApprovalDescription<InferSchemaOutput<InputSchema>> : never
   func: PikkuFunctionSessionless<
-    InferSchemaOutput<InputSchema>,
+    InputSchema extends StandardSchemaV1 ? InferSchemaOutput<InputSchema> : unknown,
     OutputSchema extends StandardSchemaV1 ? InferSchemaOutput<OutputSchema> : unknown,
     RequiredWires
   >
   auth?: boolean
-  permissions?: CorePermissionGroup<PikkuPermission<InferSchemaOutput<InputSchema>>>
+  permissions?: InputSchema extends StandardSchemaV1 ? CorePermissionGroup<PikkuPermission<InferSchemaOutput<InputSchema>>> : undefined
   middleware?: PikkuMiddleware[]
-  input: InputSchema
+  input?: InputSchema
   output?: OutputSchema
   node?: NodeConfig
+  errors?: Array<typeof PikkuError>
 }
 
 /**
@@ -435,11 +475,11 @@ export type PikkuFunctionSessionlessConfigWithSchema<
  * ```
  */
 export function pikkuSessionlessFunc<
-  InputSchema extends StandardSchemaV1,
+  InputSchema extends StandardSchemaV1 | undefined = undefined,
   OutputSchema extends StandardSchemaV1 | undefined = undefined
 >(
   config: PikkuFunctionSessionlessConfigWithSchema<InputSchema, OutputSchema, 'session' | 'rpc'>
-): PikkuFunctionConfig<InferSchemaOutput<InputSchema>, OutputSchema extends StandardSchemaV1 ? InferSchemaOutput<OutputSchema> : unknown, 'session' | 'rpc'>
+): PikkuFunctionConfig<InputSchema extends StandardSchemaV1 ? InferSchemaOutput<InputSchema> : unknown, OutputSchema extends StandardSchemaV1 ? InferSchemaOutput<OutputSchema> : unknown, 'session' | 'rpc'>
 export function pikkuSessionlessFunc<In, Out = unknown>(
   func:
     | PikkuFunctionSessionless<In, Out, 'session' | 'rpc'>
@@ -474,27 +514,23 @@ export const pikkuVoidFunc = (
 }
 
 /**
- * Creates a wrapper function for addon package functions that are exposed via RPC.
- * This allows you to wire addon functions to any wiring type (HTTP, queue, etc.)
- * without type compatibility issues.
+ * References a registered function by name for use in any wiring.
+ * Works for both local and addon functions — resolves via RPC at runtime.
  *
- * @template Name - The RPC method name (must be a key in FlattenedRPCMap)
- * @param rpcName - The name of the RPC method to invoke
- * @returns A Pikku function that proxies calls to the addon RPC method
+ * @template Name - The function name (must be a key in FlattenedRPCMap)
+ * @param rpcName - The name of the function to reference
+ * @returns A Pikku function config that proxies calls via RPC
  *
  * @example
  * ```typescript
- * // Wire an addon function via HTTP
- * wireHTTP({
- *   auth: false,
- *   method: 'get',
- *   route: '/addon/hello',
- *   func: addon('ext:hello'),
- *   tags: ['addon'],
- * })
+ * // Use in agent tools
+ * tools: [ref('todos:listTodos'), ref('myLocalFunc')]
+ *
+ * // Use in HTTP wiring
+ * wireHTTP({ route: '/greet', method: 'post', func: ref('greet') })
  * ```
  */
-export const addon = <Name extends keyof FlattenedRPCMap>(
+export const ref = <Name extends keyof FlattenedRPCMap>(
   rpcName: Name
 ): PikkuFunctionConfig<
   FlattenedRPCMap[Name]['input'],
@@ -644,5 +680,5 @@ export const addPermission = <In = unknown>(tag: string, permissions: CorePermis
   addPermissionCore(tag, permissions as any, '@pikku/addon-graph')
 }
 
-export { wireAddon } from '@pikku/core'
-export type { WireAddonConfig } from '@pikku/core'
+export { wireAddon } from '@pikku/core/rpc'
+export type { WireAddonConfig } from '@pikku/core/rpc'