@lit-protocol/vincent-ability-sdk 0.0.12-mma → 2.0.1

package/CHANGELOG.md

@@ -1,3 +1,9 @@
+## 2.0.1 (2025-09-03)
+
+### 🧱 Updated Dependencies
+
+- Updated contracts-sdk to 1.1.0
+
 # 2.0.0 (2025-08-05)
 
 ### 🚀 Features

package/dist/CHANGELOG.md

@@ -0,0 +1,70 @@
+## 2.0.1 (2025-09-03)
+
+### 🧱 Updated Dependencies
+
+- Updated contracts-sdk to 1.1.0
+
+# 2.0.0 (2025-08-05)
+
+### 🚀 Features
+
+- Add descriptions on abilities and their api interface params ([0b8ff1e3](https://github.com/LIT-Protocol/Vincent/commit/0b8ff1e3))
+
+### 🩹 Fixes
+
+- Making api version property in bundled things to ease its discovery and usage when validating its compatibility ([aa81d087](https://github.com/LIT-Protocol/Vincent/commit/aa81d087))
+- ### Implement supported Vincent Ability API range ([14f0ece1](https://github.com/LIT-Protocol/Vincent/commit/14f0ece1))
+
+  Added basic Ability API handling to ensure abilities & policies are only used by compatible abilities and policies, and with the correct version of the vincentAbilityClient / app-sdk
+
+  - Added a new jsParam when VincentAbilityClient calls an ability, `vincentAbilityApiVersion`
+  - LIT action wrappers for abilities + policies compare `vincentAbilityApiVersion` to match the major semver range the handler was built with from the ability-sdk
+  - vincentAbilityHandler() is responsible for passing along the value when it evaluates supported policies
+
+### ⚠️ Breaking Changes
+
+- Add support for vincent-contract-sdk using CBOR2 encoded policy parameters ([819fcd11](https://github.com/LIT-Protocol/Vincent/commit/819fcd11))
+- ### `error` is now `runtimeError` and can only be set by `throw ...` ([04f1ca20](https://github.com/LIT-Protocol/Vincent/commit/04f1ca20))
+
+  - Previously, if you had not defined a `deny` or `fail` schema, you could call `deny()` or `fail()` with a string
+  - That string would end up in the ability/policy response as the `error` property instead of `result`
+  - This was problematic because there was no consistent way to identify _un-handled_ error vs. _explicitly returned fail/deny results_
+  - If you don't define a deny or fail schema, you can no longer call those methods with a string.
+  - `error` is now `runtimeError`, and is _only_ set if a lifecycle method `throw`s an Error - in that case it will be the `message` property of the error
+  - If you want to be able to return simple errors in your _result_, you can define a simple deny or fail schema like `z.object({ error: z.string() }`
+
+- ### Add support for explicit `schemaValidationError` ([337a4bde](https://github.com/LIT-Protocol/Vincent/commit/337a4bde))
+
+  - Previously, a failure to validate either input or results of lifecycle method would result in `result: { zodError }` being returned
+  - Now, `result` will be `undefined` and there will be an explicit `schemaValidationError` in the result of the ability / policy
+
+  ```typescript
+  export interface SchemaValidationError {
+    zodError: ZodError<unknown>; // The result of `zod.safeParse().error`
+    phase: string; // Policies: `precheck`|`evaluate`|`commit` - Abilities: `precheck` | `execute`
+    stage: string; // `input` | `output`
+  }
+  ```
+
+### 🧱 Updated Dependencies
+
+- Updated contracts-sdk to 2.0.0
+
+### ❤️ Thank You
+
+- Daryl Collins
+- FedericoAmura @FedericoAmura
+
+## 1.0.2 (2025-07-08)
+
+### 🩹 Fixes
+
+- - Correct type of `PolicyEvaluationResultContext.deniedPolicy` so that `error` is a sibling of `result` ([edc609f5](https://github.com/LIT-Protocol/Vincent/commit/edc609f5))
+- - Fixed a case where a deny response from a policy could be returned without being parsed by its deny result schema ([27a35240](https://github.com/LIT-Protocol/Vincent/commit/27a35240))
+- - Fixed incorrect handling of failure results that resulted in `success: true` responses from abilities that returned fail results ([51087e71](https://github.com/LIT-Protocol/Vincent/commit/51087e71))
+- - Fixed `undefined` being returned to caller instead of the correct `error` string in cases where no fail result schema was defined and an explicit string was passed to `fail()` ([e8f1316a](https://github.com/LIT-Protocol/Vincent/commit/e8f1316a))
+- - Fixed ability result typeguard functions incorrectly returning `false` when they were provided outputs with no `result` (e.g. no return value schema is defined for the lifecycle method) ([cf542969](https://github.com/LIT-Protocol/Vincent/commit/cf542969))
+
+### ❤️ Thank You
+
+- Daryl Collins

package/dist/CONTRIBUTING.md

@@ -0,0 +1,123 @@
+# Contributing to Vincent Ability SDK
+
+This document provides guidelines for contributing to the Vincent Ability SDK project.
+
+## Overview
+
+The Vincent Ability SDK is an SDK exposing utilities to develop Vincent abilities and policies. It provides a type-safe lifecycle system for defining and composing policies and abilities, with strong TypeScript inference support throughout.
+
+## Setup
+
+1. Follow the global setup instructions in the repository root [CONTRIBUTING.md](../../../CONTRIBUTING.md).
+2. Install dependencies:
+   ```bash
+   pnpm install
+   ```
+
+## Development Workflow
+
+### Building
+
+Build the SDK:
+
+```bash
+nx build ability-sdk
+```
+
+### Type Checking
+
+Run type checking:
+
+```bash
+pnpm typecheck
+```
+
+### Watch Mode for Type Checking
+
+Run type checking in watch mode:
+
+```bash
+pnpm watch:type-tests
+```
+
+## Project Structure
+
+- `src/`: Source code
+  - `lib/`
+  - `type-inference-verification/`
+
+## SDK Development Guidelines
+
+1. Maintain strong TypeScript typing throughout the codebase
+2. Use Zod for schema validation
+3. Design APIs that are intuitive and easy to use
+4. Provide comprehensive documentation for all public APIs
+5. Write unit tests for all functionality
+6. Ensure backward compatibility when making changes
+
+## Core Concepts
+
+The SDK is built around these core concepts:
+
+- **Policies**: Encapsulate decision logic (precheck, evaluate, commit) and define their input/output schemas.
+- **Abilities**: Orchestrate multiple policies and expose `precheck` and `execute` lifecycle methods.
+
+## Testing
+
+Write unit tests for all functionality:
+
+```bash
+pnpm test
+```
+
+## Documentation
+
+- Document all public APIs with JSDoc comments
+- Update README.md when adding new features
+- Provide examples for common use cases
+
+## Pull Request Process
+
+1. Ensure your code follows the coding standards
+2. Update documentation if necessary
+3. Include tests for new functionality
+4. Link any related issues in your pull request description
+5. Request a review from a maintainer
+
+## For AI Editors and IDEs
+
+When working with AI-powered editors like Cursor, GitHub Copilot, or other AI assistants in this project directory, please note:
+
+### Context Priority
+
+1. **Primary Context**: When working within the ability-sdk project directory, AI editors should prioritize this CONTRIBUTING.md file and the project's README.md for specific guidance on the Ability SDK.
+
+2. **Secondary Context**: The root-level CONTRIBUTING.md and README.md files provide important context about how this SDK fits into the broader Vincent ecosystem.
+
+### Key Files for Ability SDK Context
+
+- `/packages/libs/ability-sdk/README.md`: Overview of the Ability SDK project
+- `/packages/libs/ability-sdk/CONTRIBUTING.md`: This file, with Ability SDK-specific contribution guidelines
+- `/packages/libs/ability-sdk/src/`: Source code for the Ability SDK
+
+### Related Projects
+
+The Ability SDK is a core component that is used by:
+
+- `ability-aave`: For implementing Aave abilities
+- `ability-debridge`: For implementing Debridge abilities
+- `ability-erc20-approval`: For implementing ERC20 approval abilities
+- `ability-morpho`: For implementing Morpho abilities
+- `ability-transaction-signer`: For implementing transaction signing abilities
+- `ability-uniswap-swap`: For implementing Uniswap swap abilities
+- `policy-contract-whitelist`: For implementing contract whitelist policies
+- `policy-send-counter`: For implementing transaction counter policies
+- `policy-spending-limit`: For implementing spending limit policies
+
+When working on Ability SDK code, consider these consumers for context, and focus on maintaining backward compatibility and strong type safety.
+
+## Additional Resources
+
+- [Vincent Documentation](https://docs.heyvincent.ai/)
+- [TypeScript Documentation](https://www.typescriptlang.org/docs/)
+- [Zod Documentation](https://zod.dev/)

package/dist/README.md

@@ -0,0 +1,213 @@
+# ability-sdk
+
+This library was generated with [Nx](https://nx.dev).
+
+## Building
+
+Run `nx build ability-sdk` to build the library.
+
+## Usage
+
+# Vincent Policy & Ability SDK
+
+This library provides a type-safe lifecycle system for defining and composing **policies** and **abilities**, with strong TypeScript inference support throughout.
+
+## 🧩 Core Concepts
+
+- **Policies** encapsulate decision logic (precheck, evaluate, commit) and define their input/output schemas.
+- **Abilities** orchestrate multiple policies and expose `precheck` and `execute` lifecycle methods.
+- **Context injection** provides `allow()` / `deny()` and `succeed()` / `fail()` methods, with schema-safe return typing.
+- All inference is preserved automatically using `createVincentPolicy`, `createVincentAbilityPolicy`, and `createVincentAbility`.
+
+---
+
+### 🔁 Calling `commit()` on a Policy from within a Ability
+
+Policies can define a `commit()` lifecycle method to finalize changes once an ability executes successfully. These `commit()` functions are injected automatically into the `allowedPolicies` object of the `AbilityContext`.
+
+### Example Policy (max daily spend)
+
+```ts
+import { z } from 'zod';
+import { createVincentPolicy } from '@lit-protocol/vincent-ability-sdk';
+
+import { getAmountSpentToday, adjustDailySpendAmount } from '@my-org/spending-limit-client';
+
+export const dailySpendPolicy = createVincentPolicy({
+  ipfsCid: 'policy-committable',
+  packageName: '@lit-protocol/max-spend-policy',
+
+  abilityParamsSchema: z.object({
+    buySomething: z.boolean(),
+    buyAmount: z.number(),
+  }),
+  userParamsSchema: z.object({
+    perBuyLimit: z.number(),
+    maxAmountPerDay: z.number(),
+  }),
+
+  evalAllowResultSchema: z.object({
+    ok: z.boolean(),
+    amountRemaining: z.number(),
+    amountToSpend: z.number(),
+  }),
+  evalDenyResultSchema: z.union([
+    z.object({
+      reason: z.literal('Buy amount request exceeds per-buy limit'),
+      buyAmount: z.number(),
+    }),
+    z.object({
+      reason: z.enum(['Buy amount request exceeds max amount per day']),
+      buyAmount: z.number(),
+      amountSpentToday: z.number(),
+      amountRemaining: z.number(),
+    }),
+  ]),
+
+  commitParamsSchema: z.object({ amountSpent: z.number() }),
+  commitAllowResultSchema: z.object({
+    transactionId: z.string(),
+    timestamp: z.number(),
+  }),
+  commitDenyResultSchema: z.object({
+    errorCode: z.number().optional(),
+    message: z.string(),
+  }),
+
+  evaluate: async ({ abilityParams, userParams }, context) => {
+    const { maxAmountPerDay, perBuyLimit } = userParams;
+    const { buyAmount } = abilityParams;
+
+    if (buyAmount > perBuyLimit) {
+      return context.deny({
+        reason: 'Buy amount request exceeds per-buy limit',
+        buyAmount,
+      });
+    }
+
+    const amountSpentToday = await getAmountSpentToday(context.delegation.delegator);
+    const amountRemaining = maxAmountPerDay - amountSpentToday;
+
+    if (buyAmount > amountRemaining) {
+      return context.deny({
+        reason: 'Buy amount request exceeds max amount per day',
+        amountSpentToday,
+        buyAmount,
+        amountRemaining,
+      });
+    }
+
+    return context.allow({
+      ok: true,
+      amountRemaining,
+      amountToSpend: buyAmount,
+    });
+  },
+
+  commit: async ({ amountSpent }, context) => {
+    try {
+      const spendCommitResult: { transactionId: string; timestamp: number } =
+        await adjustDailySpendAmount(context.delegation.delegator, amountSpent);
+
+      return context.allow(spendCommitResult);
+    } catch (e: unknown) {
+      if (e instanceof Error) {
+        if ('errorCode' in e) {
+          return context.deny({
+            errorCode: e.errorCode as number,
+            message: e.message,
+          });
+        } else {
+          return context.deny({ message: e.message });
+        }
+      }
+
+      return context.deny({ message: String(e) });
+    }
+  },
+});
+```
+
+---
+
+### Example Ability - Uniswap
+
+```ts
+import { z } from 'zod';
+
+import {
+  createVincentAbilityPolicy,
+  createVincentAbility,
+} from '@lit-protocol/vincent-ability-sdk';
+
+import { dailySpendPolicy } from '@lit-protocol/max-spend-policy';
+
+import uniswapV3Client from '@uniswap/v3-sdk';
+
+const abilityParamsSchema = z.object({
+  buy: z.boolean(),
+  buyAmount: z.number(),
+});
+
+export const myTokenSwapAbility = createVincentAbility({
+  packageName: 'tokenswapability',
+  abilityDescription: 'Token Swap Ability',
+
+  abilityParamsSchema,
+
+  supportedPolicies: [
+    createVincentAbilityPolicy({
+      abilityParamsSchema,
+      PolicyConfig: dailySpendPolicy,
+      abilityParameterMappings: { buy: 'buyAmount' },
+    }),
+  ],
+  executeSuccessSchema: z.object({
+    message: z.string(),
+    amountSpent: z.number().optional(),
+    spendCommitResult: z
+      .object({
+        transactionId: z.string(),
+        timestamp: z.number(),
+      })
+      .optional(),
+  }),
+
+  executeFailSchema: z.object({ error: z.string(), message: z.string() }),
+
+  async execute(abilityParams, { succeed, fail, policiesContext }) {
+    const spendPolicyContext = policiesContext.allowedPolicies['@lit-protocol/max-spend-policy'];
+
+    const amountSpent: number = await uniswapV3Client.performSwap({});
+
+    if (spendPolicyContext) {
+      const spendCommitResult = await spendPolicyContext.commit({
+        amountSpent,
+      });
+
+      if (!spendCommitResult.allow) {
+        return fail({
+          error: `Policy commit denied with code ${spendCommitResult.result.errorCode}`,
+          message: 'Ability executed but policy commit denied',
+        });
+      }
+
+      if (spendCommitResult.allow) {
+        return succeed({
+          amountSpent,
+          spendCommitResult: spendCommitResult.result,
+          message: 'Ability executed and spending limit policy commit completed',
+        });
+      }
+    }
+
+    return succeed({
+      message: 'Ability executed for user without enabled spending limit',
+    });
+  },
+});
+```
+
+## 🧠 Tip
+
+Ability and policy authors should export the result of `createVincentPolicy()` / `createVincentAbility()`

package/dist/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lit-protocol/vincent-ability-sdk",
-  "version": "2.0.0",
+  "version": "2.0.1",
   "publishConfig": {
     "access": "public"
   },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lit-protocol/vincent-ability-sdk",
-  "version": "0.0.12-mma",
+  "version": "2.0.1",
   "publishConfig": {
     "access": "public"
   },
@@ -9,7 +9,7 @@
     "semver": "^7.7.2",
     "tslib": "^2.8.1",
     "zod": "^3.25.64",
-    "@lit-protocol/vincent-contracts-sdk": "0.0.12-mma"
+    "@lit-protocol/vincent-contracts-sdk": "1.1.0"
   },
   "main": "./dist/src/index.js",
   "types": "./dist/src/index.d.ts",