@lit-protocol/vincent-app-sdk 1.0.0-1

package/CHANGELOG.md

@@ -0,0 +1,53 @@
+## 0.0.7 (2025-05-26)
+
+### 🚀 Features
+
+- improved mcp api doc ([0389014](https://github.com/LIT-Protocol/Vincent/commit/0389014))
+- updated Vincent MCP documentation with its own section ([3457891](https://github.com/LIT-Protocol/Vincent/commit/3457891))
+- add documentation ([f539eb5](https://github.com/LIT-Protocol/Vincent/commit/f539eb5))
+- implementation of the vincent mcp server stdio and http runners using the app to mcp transformer in the sdk ([aa58c17](https://github.com/LIT-Protocol/Vincent/commit/aa58c17))
+- implementation of the vincent app mcp wrapper ([02dd8ca](https://github.com/LIT-Protocol/Vincent/commit/02dd8ca))
+- add release script to release SDK and its doc to npm and vercel ([eaccd5f](https://github.com/LIT-Protocol/Vincent/commit/eaccd5f))
+- **docs:** change title, downgrade for plugin extras ([cdd62c0](https://github.com/LIT-Protocol/Vincent/commit/cdd62c0))
+- use standard syntax for jwt validation errors and move validation to decoding step ([fefbbc6](https://github.com/LIT-Protocol/Vincent/commit/fefbbc6))
+- deduplicate vincent data in decoded jwt and revert building config changes ([481d131](https://github.com/LIT-Protocol/Vincent/commit/481d131))
+- change ts compiler config to increase compatibility surface and fix usage in DCA FE vite app ([027582d](https://github.com/LIT-Protocol/Vincent/commit/027582d))
+- add authorized app and user info to jwt ([237f70d](https://github.com/LIT-Protocol/Vincent/commit/237f70d))
+- **vincent-app-sdk:** add Express authentication helpers and update docs ([14a04b3](https://github.com/LIT-Protocol/Vincent/commit/14a04b3))
+- **vincent-app-sdk:** Update README.md ([d052e18](https://github.com/LIT-Protocol/Vincent/commit/d052e18))
+- **vincent-app-sdk:** Add sdk-docs TypeDocs to root of repo ([fb15599](https://github.com/LIT-Protocol/Vincent/commit/fb15599))
+- **vincent-app-sdk:** Return both the original JWT string and the decoded JWT object from `decodeVincentLoginJWT()` - Also fixed inverted logic check for `isLoginUri()`, and converted to object params for `isLoginUri()` ([c2f3a19](https://github.com/LIT-Protocol/Vincent/commit/c2f3a19))
+- **vincent-app-sdk:** Add `removeLoginJWTFromURI()` method to `VincentWebAppClient` ([17072f4](https://github.com/LIT-Protocol/Vincent/commit/17072f4))
+- **vincent-app-sdk:** Replace `pkp/delegatee-sigs` with a `VincentToolClient` - Exposes a single method, `getVincentToolClient()`, which Vincent app developers will use to interact with Vincent Tool LIT actions - Fixes existing code that created new instances of LitNodeClient and connecting to them every time the tool is interacted with, using newly minted singleton module - Initial TSDoc configurations for exposing the tool client construction and usage under a 'Vincent Tools' category. ([2052ebe](https://github.com/LIT-Protocol/Vincent/commit/2052ebe))
+- **vincent-app-sdk:** Define an internal module for managing a singleton instance of a LitNodeClient ([d297b0c](https://github.com/LIT-Protocol/Vincent/commit/d297b0c))
+- update vincent sdk readme ([090614d](https://github.com/LIT-Protocol/Vincent/commit/090614d))
+- added contracts class ([ef1851e](https://github.com/LIT-Protocol/Vincent/commit/ef1851e))
+
+### 🩹 Fixes
+
+- ZodSchemmaMap typo ([095f38e](https://github.com/LIT-Protocol/Vincent/commit/095f38e))
+- doc reference ([b1450f8](https://github.com/LIT-Protocol/Vincent/commit/b1450f8))
+- remove unnecessary type annotation ([c71eeac](https://github.com/LIT-Protocol/Vincent/commit/c71eeac))
+- sdk nx project linting tool ([82dd819](https://github.com/LIT-Protocol/Vincent/commit/82dd819))
+- **docs:** rename (remove API) ([a4b8e83](https://github.com/LIT-Protocol/Vincent/commit/a4b8e83))
+- **docs:** formatting fixes, custom css for :::info ([6f2fcef](https://github.com/LIT-Protocol/Vincent/commit/6f2fcef))
+- **vincent-app-sdk:** Fix import of `JWT_ERROR` to import from root of `did-jwt` package ([dd96111](https://github.com/LIT-Protocol/Vincent/commit/dd96111))
+- do not export simple jwt manipulating functions. Consumers should use the sdk directly ([6e46eee](https://github.com/LIT-Protocol/Vincent/commit/6e46eee))
+- **publish:** need to include 'dist' ([ecf38c3](https://github.com/LIT-Protocol/Vincent/commit/ecf38c3))
+- **sdk:** package.json exports ([dd35563](https://github.com/LIT-Protocol/Vincent/commit/dd35563))
+- no need types node ([af98c0e](https://github.com/LIT-Protocol/Vincent/commit/af98c0e))
+- **build:** add missing tsconfig.lib.json ([ce47c23](https://github.com/LIT-Protocol/Vincent/commit/ce47c23))
+- **jest:** enable `passWithNoTests` ([0f4ac57](https://github.com/LIT-Protocol/Vincent/commit/0f4ac57))
+- lint and any ([c4fc2ab](https://github.com/LIT-Protocol/Vincent/commit/c4fc2ab))
+- **deps:** correctly scope dependencies between global & individual packages ([b3fdb8c](https://github.com/LIT-Protocol/Vincent/commit/b3fdb8c))
+- **build:** remove rollup and use default nx settings ([b3769df](https://github.com/LIT-Protocol/Vincent/commit/b3769df))
+- minor changes ([0a70d4a](https://github.com/LIT-Protocol/Vincent/commit/0a70d4a))
+- removed umd build ([6e532fa](https://github.com/LIT-Protocol/Vincent/commit/6e532fa))
+
+### ❤️ Thank You
+
+- Ansh Saxena @anshss
+- Anson
+- awisniew207 @awisniew207
+- Daryl Collins
+- FedericoAmura @FedericoAmura

package/CONTRIBUTING.md

@@ -0,0 +1,115 @@
+# Contributing to Vincent SDK
+
+This document provides guidelines for contributing to the Vincent SDK project.
+
+## Overview
+
+The Vincent SDK is a TypeScript SDK that exposes useful tools to interact with Vincent systems in web or Node.js environments. It provides client libraries for both frontend applications and backend services.
+
+## 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
+pnpm build
+```
+
+### Documentation
+
+Generate TypeDoc documentation:
+
+```bash
+pnpm typedoc
+```
+
+## Project Structure
+
+- `src/`: Source code
+  - `index.ts`: Main entry point
+  - `app/`: Web utilities to authenticate against Vincent Apps in clients
+  - `express-authentication-middleware/`: Express middleware wrapper to properly validate clients JWT server side
+  - `jwt/`: Utility functions to work with Vincent JWT between Vincent Apps client and server
+  - `tool/`: Utility functions to work with Vincent Tools
+
+## SDK Components
+
+### VincentWebAppClient
+
+The Vincent Web App Client provides methods for managing user authentication, JWT tokens, and consent flows in Vincent applications.
+
+### VincentToolClient
+
+The Vincent Tool Client uses an ethers signer for your delegatee account to run Vincent Tools on behalf of your app users.
+
+## Coding Standards
+
+1. Use TypeScript for all new code
+2. Follow the project's existing coding style
+3. Write clear, descriptive comments and JSDoc for public APIs
+4. Include appropriate error handling
+5. Write unit tests for new functionality
+6. Maintain backward compatibility when possible
+
+## Type Safety
+
+- Use proper TypeScript types for all functions and variables
+- Avoid using `any` type; prefer `unknown` when the type is truly unknown
+- Use generics where appropriate to maintain type safety
+- Ensure exported APIs have proper type definitions
+
+## Testing
+
+Write unit tests for new functionality:
+
+```bash
+pnpm test
+```
+
+## Documentation
+
+- Document all public APIs with JSDoc comments
+- Update README.md when adding new features
+- Generate and review TypeDoc documentation
+
+## Pull Request Process
+
+1. Ensure your code follows the coding standards
+2. Update documentation if necessary
+3. Include tests for new features or bug fixes
+4. Link any related issues in your pull request description
+5. Add an nx version plan documenting your changes
+6. 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 SDK project directory, AI editors should prioritize this CONTRIBUTING.md file and the project's README.md for specific guidance on the SDK project.
+
+2. **Secondary Context**: The root-level CONTRIBUTING.md and README.md files provide important context about how this project fits into the broader Vincent ecosystem.
+
+### Key Files for SDK Context
+
+- `/packages/libs/app-sdk/README.md`: Overview of the SDK project
+- `/packages/libs/app-sdk/CONTRIBUTING.md`: This file, with SDK-specific contribution guidelines
+- `/packages/libs/app-sdk/src/`: Source code for the SDK
+
+When working on SDK code, consider these dependencies and consumers for context.
+
+## Additional Resources
+
+- [Vincent Documentation](https://docs.heyvincent.ai/)
+- [SDK Documentation](https://sdk-docs.heyvincent.ai/)
+- [TypeScript Documentation](https://www.typescriptlang.org/docs/)

package/README.md

@@ -0,0 +1,215 @@
+# Vincent SDK
+
+## Installation
+
+```
+npm install @lit-protocol/vincent-app-sdk
+```
+
+## Usage
+
+# Client (Web)
+
+## VincentWebAppClient
+
+The Vincent Web App Client provides methods for managing user authentication, JWT tokens, and consent flows in Vincent applications.
+
+### Methods
+
+#### redirectToConsentPage()
+
+Redirects the user to the Vincent consent page to obtain authorization. Once the user has completed the vincent consent flow
+they will be redirected back to your app with a signed JWT that you can use to authenticate requests against your backend APIs
+
+- When a JWT is expired, you need to use this method to get a new JWT
+
+#### isLoginUri()
+
+Checks if the current window location contains a Vincent login JWT. You can use this method to know that you should update login state with the newly provided JWT
+
+- Returns: Boolean indicating if the URI contains a login JWT
+
+#### decodeVincentLoginJWT(expectedAudience)
+
+Decodes a Vincent login JWT. Performs basic sanity check but does not perform full verify() logic. You will want to run `verify()` from the jwt tools to verify the JWT is fully valid and not expired etc.
+
+- The expected audience is typically your app's domain -- it should be one of your valid redirectUri values from your Vincent app configuration
+
+- Returns: An object containing both the original JWT string and the decoded JWT object
+
+#### removeLoginJWTFromURI()
+
+Removes the login JWT parameter from the current URI. Call this after you have verified and stored the JWT for later usage.
+
+### Basic Usage
+
+```typescript
+import { getVincentWebAppClient, jwt } from '@lit-protocol/vincent-app-sdk';
+
+const { isExpired } = jwt;
+
+const vincentAppClient = getVincentWebAppClient({ appId: MY_APP_ID });
+// ... In your app logic:
+if (vincentAppClient.isLogin()) {
+  // Handle app logic for the user has just logged in
+  const { decoded, jwt } = vincentAppClient.decodeVincentLoginJWT(window.location.origin);
+  // Store `jwt` for later usage; the user is now logged in.
+} else {
+  // Handle app logic for the user is _already logged in_ (check for stored & unexpired JWT)
+
+  const jwt = localStorage.getItem('VINCENT_AUTH_JWT');
+  if (jwt && isExpired(jwt)) {
+    // User must re-log in
+    vincentAppClient.redirectToConsentPage({ redirectUri: window.location.href });
+  }
+
+  if (!jwt) {
+    // Handle app logic for the user is not yet logged in
+    vincentAppClient.redirectToConsentPage({ redirectUri: window.location.href });
+  }
+}
+```
+
+# Backend
+
+In your backend, you will have to verify the JWT to make sure the user has granted you the required permissions to act on their behalf.
+
+## VincentToolClient
+
+The Vincent Tool Client uses an ethers signer for your delegatee account to run Vincent Tools on behalf of your app users.
+
+This client will typically be used by an AI agent or your app backend service, as it requires a signer that conforms to the ethers v5 signer API, and with access to your delegatee account's private key to authenticate with the LIT network when executing the Vincent Tool.
+
+### Configuration
+
+```typescript
+interface VincentToolClientConfig {
+  ethersSigner: ethers.Signer; // An ethers v5 compatible signer
+  vincentToolCid: string; // The CID of the Vincent Tool to execute
+}
+```
+
+### Methods
+
+#### execute(params: VincentToolParams): Promise<ExecuteJsResponse>
+
+Executes a Vincent Tool with the provided parameters.
+
+- `params`: Record<string, unknown> - Parameters to pass to the Vincent Tool
+- Returns: Promise resolving to an ExecuteJsResponse from the LIT network
+
+### Tool execution
+
+```typescript
+import { getVincentToolClient } from '@lit-protocol/vincent-app-sdk';
+// Import the tool you want to execute
+import { bundledVincentTool as erc20BundledTool } from '@lit-protocol/vincent-tool-erc20-approval';
+
+// One of delegatee signers from your app's Vincent Dashboard
+const delegateeSigner = new ethers.Wallet('YOUR_DELEGATEE_PRIVATE_KEY');
+
+// Initialize the Vincent Tool Client
+const toolClient = getVincentToolClient({
+  ethersSigner: delegateeSigner,
+  bundledVincentTool: erc20BundledTool,
+});
+const delegatorPkpEthAddress = '0x09182301238';
+
+const toolParams = {
+  // Fill with the params your tool needs
+};
+
+// Run precheck to see if tool should be executed
+const precheckResult = await client.precheck(toolParams, {
+  delegatorPkpEthAddress,
+});
+
+if (precheckResult.success === true) {
+  // Execute the Vincent Tool
+  const executeResult = await client.execute(toolParams, {
+    delegatorPkpEthAddress,
+  });
+
+  // ...tool has executed, you can check `executeResult` for details
+}
+```
+
+### Usage
+
+### Authentication
+
+A basic Express authentication middleware factory function is provided with the SDK.
+
+- Create an express middleware using `getAuthenticateUserExpressHandler()`
+- Once you have added the middleware to your route, use `authenticatedRequestHandler()` to provide
+  type-safe access to `req.user` in your downstream RequestHandler functions.
+- When defining your authenticated routes, use the `ExpressAuthHelpers` type to type your functions and function arguments.
+
+See getAuthenticateUserExpressHandler() documentation to see the source for the express authentication route handler
+
+```typescript
+import { expressAuthHelpers } from '@lit-protocol/vincent-app-sdk';
+const { authenticatedRequestHandler, getAuthenticateUserExpressHandler } = expressAuthHelpers;
+
+import type { ExpressAuthHelpers } from '@lit-protocol/vincent-app-sdk';
+
+const { ALLOWED_AUDIENCE } = process.env;
+
+const authenticateUserMiddleware = getAuthenticateUserExpressHandler(ALLOWED_AUDIENCE);
+
+// Define an authenticated route handler
+const getUserProfile = async (req: ExpressAuthHelpers['AuthenticatedRequest'], res: Response) => {
+  // Access authenticated user information
+  const { pkpAddress } = req.user;
+
+  // Fetch and return user data
+  const userData = await userRepository.findByAddress(pkpAddress);
+  res.json(userData);
+};
+
+// Use in Express route with authentication
+app.get('/profile', authenticateUser, authenticatedRequestHandler(getUserProfile));
+```
+
+## JWT Authentication
+
+### Overview
+
+The JWT authentication system in Vincent SDK allows for secure communication between user applications and Vincent Tools. JWTs are used to verify user consent and authorize tool executions.
+
+### Authentication Flow
+
+1. User initiates an action requiring Vincent Tool access
+2. Application redirects to the Vincent consent page using `VincentWebAppClient.redirectToConsentPage()`
+3. User provides consent for the requested tools/policies
+4. User is redirected back to the application with a JWT in the URL
+5. Application validates and stores the JWT using `VincentWebAppClient` methods
+6. JWT is used to authenticate with the app backend
+
+### JWT Structure
+
+Vincent JWTs contain:
+
+- User account identity information (pkpAddress and pkpPublicKey)
+- Expiration timestamp
+- Signature from the Vincent authorization service
+
+### Error Handling
+
+When JWT validation fails, descriptive error messages are thrown to help with troubleshooting.
+
+### Usage Notes
+
+- JWTs have an expiration time after which they are no longer valid
+- When a JWT expires, redirect the user to the consent page to obtain a new one using the `VincentWebAppClient`
+
+## Release
+
+Pre-requisites:
+
+- You will need a valid npm account with access to the `@lit-protocol` organization.
+- Run `pnpm vercel login` at sdk root to get a authentication token for vercel
+- Also you will need to fill the `.env` file with the vercel project and org ids for the [vincent-docs](https://vercel.com/lit-protocol/vincent-docs) project.
+
+Then run `pnpm release` on the repository root. It will prompt you to update the Vincent SDK version and then ask you to confirm the release.
+This process will also generate a `CHANGELOG.md` record with the changes for the release and update typedoc in vercel after publishing the SDK.

package/dist/CHANGELOG.md

@@ -0,0 +1,53 @@
+## 0.0.7 (2025-05-26)
+
+### 🚀 Features
+
+- improved mcp api doc ([0389014](https://github.com/LIT-Protocol/Vincent/commit/0389014))
+- updated Vincent MCP documentation with its own section ([3457891](https://github.com/LIT-Protocol/Vincent/commit/3457891))
+- add documentation ([f539eb5](https://github.com/LIT-Protocol/Vincent/commit/f539eb5))
+- implementation of the vincent mcp server stdio and http runners using the app to mcp transformer in the sdk ([aa58c17](https://github.com/LIT-Protocol/Vincent/commit/aa58c17))
+- implementation of the vincent app mcp wrapper ([02dd8ca](https://github.com/LIT-Protocol/Vincent/commit/02dd8ca))
+- add release script to release SDK and its doc to npm and vercel ([eaccd5f](https://github.com/LIT-Protocol/Vincent/commit/eaccd5f))
+- **docs:** change title, downgrade for plugin extras ([cdd62c0](https://github.com/LIT-Protocol/Vincent/commit/cdd62c0))
+- use standard syntax for jwt validation errors and move validation to decoding step ([fefbbc6](https://github.com/LIT-Protocol/Vincent/commit/fefbbc6))
+- deduplicate vincent data in decoded jwt and revert building config changes ([481d131](https://github.com/LIT-Protocol/Vincent/commit/481d131))
+- change ts compiler config to increase compatibility surface and fix usage in DCA FE vite app ([027582d](https://github.com/LIT-Protocol/Vincent/commit/027582d))
+- add authorized app and user info to jwt ([237f70d](https://github.com/LIT-Protocol/Vincent/commit/237f70d))
+- **vincent-app-sdk:** add Express authentication helpers and update docs ([14a04b3](https://github.com/LIT-Protocol/Vincent/commit/14a04b3))
+- **vincent-app-sdk:** Update README.md ([d052e18](https://github.com/LIT-Protocol/Vincent/commit/d052e18))
+- **vincent-app-sdk:** Add sdk-docs TypeDocs to root of repo ([fb15599](https://github.com/LIT-Protocol/Vincent/commit/fb15599))
+- **vincent-app-sdk:** Return both the original JWT string and the decoded JWT object from `decodeVincentLoginJWT()` - Also fixed inverted logic check for `isLoginUri()`, and converted to object params for `isLoginUri()` ([c2f3a19](https://github.com/LIT-Protocol/Vincent/commit/c2f3a19))
+- **vincent-app-sdk:** Add `removeLoginJWTFromURI()` method to `VincentWebAppClient` ([17072f4](https://github.com/LIT-Protocol/Vincent/commit/17072f4))
+- **vincent-app-sdk:** Replace `pkp/delegatee-sigs` with a `VincentToolClient` - Exposes a single method, `getVincentToolClient()`, which Vincent app developers will use to interact with Vincent Tool LIT actions - Fixes existing code that created new instances of LitNodeClient and connecting to them every time the tool is interacted with, using newly minted singleton module - Initial TSDoc configurations for exposing the tool client construction and usage under a 'Vincent Tools' category. ([2052ebe](https://github.com/LIT-Protocol/Vincent/commit/2052ebe))
+- **vincent-app-sdk:** Define an internal module for managing a singleton instance of a LitNodeClient ([d297b0c](https://github.com/LIT-Protocol/Vincent/commit/d297b0c))
+- update vincent sdk readme ([090614d](https://github.com/LIT-Protocol/Vincent/commit/090614d))
+- added contracts class ([ef1851e](https://github.com/LIT-Protocol/Vincent/commit/ef1851e))
+
+### 🩹 Fixes
+
+- ZodSchemmaMap typo ([095f38e](https://github.com/LIT-Protocol/Vincent/commit/095f38e))
+- doc reference ([b1450f8](https://github.com/LIT-Protocol/Vincent/commit/b1450f8))
+- remove unnecessary type annotation ([c71eeac](https://github.com/LIT-Protocol/Vincent/commit/c71eeac))
+- sdk nx project linting tool ([82dd819](https://github.com/LIT-Protocol/Vincent/commit/82dd819))
+- **docs:** rename (remove API) ([a4b8e83](https://github.com/LIT-Protocol/Vincent/commit/a4b8e83))
+- **docs:** formatting fixes, custom css for :::info ([6f2fcef](https://github.com/LIT-Protocol/Vincent/commit/6f2fcef))
+- **vincent-app-sdk:** Fix import of `JWT_ERROR` to import from root of `did-jwt` package ([dd96111](https://github.com/LIT-Protocol/Vincent/commit/dd96111))
+- do not export simple jwt manipulating functions. Consumers should use the sdk directly ([6e46eee](https://github.com/LIT-Protocol/Vincent/commit/6e46eee))
+- **publish:** need to include 'dist' ([ecf38c3](https://github.com/LIT-Protocol/Vincent/commit/ecf38c3))
+- **sdk:** package.json exports ([dd35563](https://github.com/LIT-Protocol/Vincent/commit/dd35563))
+- no need types node ([af98c0e](https://github.com/LIT-Protocol/Vincent/commit/af98c0e))
+- **build:** add missing tsconfig.lib.json ([ce47c23](https://github.com/LIT-Protocol/Vincent/commit/ce47c23))
+- **jest:** enable `passWithNoTests` ([0f4ac57](https://github.com/LIT-Protocol/Vincent/commit/0f4ac57))
+- lint and any ([c4fc2ab](https://github.com/LIT-Protocol/Vincent/commit/c4fc2ab))
+- **deps:** correctly scope dependencies between global & individual packages ([b3fdb8c](https://github.com/LIT-Protocol/Vincent/commit/b3fdb8c))
+- **build:** remove rollup and use default nx settings ([b3769df](https://github.com/LIT-Protocol/Vincent/commit/b3769df))
+- minor changes ([0a70d4a](https://github.com/LIT-Protocol/Vincent/commit/0a70d4a))
+- removed umd build ([6e532fa](https://github.com/LIT-Protocol/Vincent/commit/6e532fa))
+
+### ❤️ Thank You
+
+- Ansh Saxena @anshss
+- Anson
+- awisniew207 @awisniew207
+- Daryl Collins
+- FedericoAmura @FedericoAmura

package/dist/CONTRIBUTING.md

@@ -0,0 +1,115 @@
+# Contributing to Vincent SDK
+
+This document provides guidelines for contributing to the Vincent SDK project.
+
+## Overview
+
+The Vincent SDK is a TypeScript SDK that exposes useful tools to interact with Vincent systems in web or Node.js environments. It provides client libraries for both frontend applications and backend services.
+
+## 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
+pnpm build
+```
+
+### Documentation
+
+Generate TypeDoc documentation:
+
+```bash
+pnpm typedoc
+```
+
+## Project Structure
+
+- `src/`: Source code
+  - `index.ts`: Main entry point
+  - `app/`: Web utilities to authenticate against Vincent Apps in clients
+  - `express-authentication-middleware/`: Express middleware wrapper to properly validate clients JWT server side
+  - `jwt/`: Utility functions to work with Vincent JWT between Vincent Apps client and server
+  - `tool/`: Utility functions to work with Vincent Tools
+
+## SDK Components
+
+### VincentWebAppClient
+
+The Vincent Web App Client provides methods for managing user authentication, JWT tokens, and consent flows in Vincent applications.
+
+### VincentToolClient
+
+The Vincent Tool Client uses an ethers signer for your delegatee account to run Vincent Tools on behalf of your app users.
+
+## Coding Standards
+
+1. Use TypeScript for all new code
+2. Follow the project's existing coding style
+3. Write clear, descriptive comments and JSDoc for public APIs
+4. Include appropriate error handling
+5. Write unit tests for new functionality
+6. Maintain backward compatibility when possible
+
+## Type Safety
+
+- Use proper TypeScript types for all functions and variables
+- Avoid using `any` type; prefer `unknown` when the type is truly unknown
+- Use generics where appropriate to maintain type safety
+- Ensure exported APIs have proper type definitions
+
+## Testing
+
+Write unit tests for new functionality:
+
+```bash
+pnpm test
+```
+
+## Documentation
+
+- Document all public APIs with JSDoc comments
+- Update README.md when adding new features
+- Generate and review TypeDoc documentation
+
+## Pull Request Process
+
+1. Ensure your code follows the coding standards
+2. Update documentation if necessary
+3. Include tests for new features or bug fixes
+4. Link any related issues in your pull request description
+5. Add an nx version plan documenting your changes
+6. 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 SDK project directory, AI editors should prioritize this CONTRIBUTING.md file and the project's README.md for specific guidance on the SDK project.
+
+2. **Secondary Context**: The root-level CONTRIBUTING.md and README.md files provide important context about how this project fits into the broader Vincent ecosystem.
+
+### Key Files for SDK Context
+
+- `/packages/libs/app-sdk/README.md`: Overview of the SDK project
+- `/packages/libs/app-sdk/CONTRIBUTING.md`: This file, with SDK-specific contribution guidelines
+- `/packages/libs/app-sdk/src/`: Source code for the SDK
+
+When working on SDK code, consider these dependencies and consumers for context.
+
+## Additional Resources
+
+- [Vincent Documentation](https://docs.heyvincent.ai/)
+- [SDK Documentation](https://sdk-docs.heyvincent.ai/)
+- [TypeScript Documentation](https://www.typescriptlang.org/docs/)