@campnetwork/origin 1.2.0-1 → 1.2.0-3

package/README.md

@@ -17,9 +17,21 @@ The Origin SDK currently exposes the following modules:
 - `"@campnetwork/origin"` - The main entry point for the SDK, exposes the following classes:
   - `TwitterAPI` - For fetching user Twitter data from Origin
   - `SpotifyAPI` - For fetching user Spotify data from Origin
-  - `Auth` - For authenticating users with the Origin SDK
+  - `Auth` - For authenticating users with the Origin SDK (browser and Node.js)
+  - Signer adapters and utilities for Node.js support (ethers, viem, custom signers)
+  - Camp Network chain configurations (`campMainnet`, `campTestnet`)
+  - Origin utilities (`createLicenseTerms`, `LicenseTerms`, `DataStatus`)
 - `"@campnetwork/origin/react"` - Exposes the CampProvider and CampContext, as well as React components and hooks for authentication and fetching user data via Origin
 
+## Features
+
+- **Browser & Node.js Support** - Use in client-side and server-side applications
+- **Multiple Signer Types** - Works with ethers, viem, or custom signers
+- **Social Account Linking** - Connect Twitter, Spotify, and TikTok
+- **React Components** - Pre-built UI components and hooks
+- **TypeScript Support** - Full type definitions included
+- **Flexible Storage** - Custom storage adapters for session persistence
+
 # Installation
 
 ```bash
@@ -262,8 +274,6 @@ const video = await tiktok.fetchVideo("jack", "1234567890");
 
 The Auth class is the entry point for authenticating users with the Origin SDK. It requires a clientId to be instantiated.
 
-**Note: The Auth class is only to be used on the client side.**
-
 ### Constructor
 
 - `clientId` - The client ID of your app. This is required to authenticate users with the Origin SDK.
@@ -430,6 +440,8 @@ After the user has authenticated, the following methods can be used to link and
 When linking a social account, the user will be redirected to the OAuth flow for that social platform.
 Afterwards, the user will be redirected back to the `redirectUri` specified in the Auth constructor.
 
+**Note: Linking socials is only available in a browser environment**
+
 #### linkTwitter
 
 `linkTwitter() => void`
@@ -492,6 +504,191 @@ The `unlinkTikTok` method unlinks the user's TikTok account from Origin.
 await auth.unlinkTikTok();
 ```
 
+## Node.js Support
+
+The Origin SDK supports Node.js environments, allowing you to authenticate and interact with Origin using server-side signers like ethers or viem.
+
+### Installation for Node.js
+
+```bash
+# With ethers
+npm install @campnetwork/origin ethers
+
+# With viem
+npm install @campnetwork/origin viem
+```
+
+### Key Differences from Browser Usage
+
+1. **No Browser Provider Detection**: In Node.js, you explicitly provide a signer instead of detecting browser wallets
+2. **Storage**: By default, Node.js uses in-memory storage (not persisted). You can provide a custom storage adapter
+3. **OAuth Social Linking**: Social account linking requires browser environment for OAuth flow
+4. **SIWE Domain/URI**: You must provide domain and URI for SIWE messages
+
+### Using with ethers
+
+```js
+import { Auth, campMainnet } from "@campnetwork/origin";
+import { ethers } from "ethers";
+
+// Setup ethers provider and signer
+const provider = new ethers.JsonRpcProvider(
+  process.env.RPC_URL || campMainnet.rpcUrls.default.http[0]
+);
+const signer = new ethers.Wallet(process.env.PRIVATE_KEY, provider);
+
+// Create Auth instance
+const auth = new Auth({
+  clientId: process.env.CLIENT_ID,
+  redirectUri: "https://myapp.com/callback",
+  environment: "PRODUCTION",
+});
+
+// Connect using ethers signer
+const result = await auth.connectWithSigner(signer, {
+  domain: "myapp.com",
+  uri: "https://myapp.com",
+});
+
+console.log("Connected!", result.walletAddress);
+
+// Use origin methods
+if (auth.origin) {
+  const terms = await auth.origin.getTerms(tokenId);
+  console.log("Terms:", terms);
+}
+```
+
+### Using with viem
+
+```js
+import { Auth, createNodeWalletClient, campMainnet } from "@campnetwork/origin";
+import { privateKeyToAccount } from "viem/accounts";
+
+// Create viem account from private key
+const account = privateKeyToAccount(process.env.PRIVATE_KEY);
+
+// Create wallet client for Node.js using Camp Network chain
+const client = createNodeWalletClient(
+  account,
+  campMainnet,
+  process.env.RPC_URL || campMainnet.rpcUrls.default.http[0]
+);
+
+// Create Auth instance
+const auth = new Auth({
+  clientId: process.env.CLIENT_ID,
+  redirectUri: "https://myapp.com/callback",
+  environment: "PRODUCTION",
+});
+
+// Connect using viem client
+await auth.connectWithSigner(client, {
+  domain: "myapp.com",
+  uri: "https://myapp.com",
+});
+
+console.log("Authenticated:", auth.isAuthenticated);
+```
+
+### Exported Chain Configurations
+
+The SDK exports Camp Network chain configurations for easy use:
+
+```js
+import { campMainnet, campTestnet } from "@campnetwork/origin";
+
+// campMainnet - Chain ID: 484 (Production)
+// campTestnet - Chain ID: 123420001114 (Basecamp testnet)
+
+console.log(campMainnet.rpcUrls.default.http[0]); // RPC URL
+console.log(campMainnet.blockExplorers.default.url); // Block explorer
+```
+
+### Custom Storage Adapter
+
+By default, Node.js uses in-memory storage. You can provide a custom storage adapter for persistence:
+
+```js
+import { Auth, MemoryStorage } from "@campnetwork/origin";
+
+// Custom file-based storage
+class FileStorage {
+  async getItem(key) {
+    /* read from file */
+  }
+  async setItem(key, value) {
+    /* write to file */
+  }
+  async removeItem(key) {
+    /* delete from file */
+  }
+}
+
+const auth = new Auth({
+  clientId: process.env.CLIENT_ID,
+  redirectUri: "https://myapp.com/callback",
+  environment: "PRODUCTION",
+  storage: new FileStorage(), // Custom storage
+});
+```
+
+### Methods
+
+#### connectWithSigner
+
+`connectWithSigner(signer: any, options?: { domain?: string, uri?: string }) => Promise<{ success: boolean, message: string, walletAddress: string }>`
+
+Connect with a custom signer (viem WalletClient, ethers Signer, or custom signer implementation).
+
+```js
+await auth.connectWithSigner(signer, {
+  domain: "myapp.com", // Required: Your application domain
+  uri: "https://myapp.com", // Required: Your application URI
+});
+```
+
+**Supported Signer Types:**
+
+- **viem WalletClient** - Automatically detected and used
+- **ethers Signer** (v5 or v6) - Works with both versions
+- **Custom Signer** - Must implement `getAddress()`, `signMessage()`, and `getChainId()` methods
+
+### Exported Types and Utilities
+
+```js
+import {
+  // Auth class
+  Auth,
+
+  // Signer adapters
+  ViemSignerAdapter,
+  EthersSignerAdapter,
+  CustomSignerAdapter,
+  createSignerAdapter,
+
+  // Storage adapters
+  BrowserStorage,
+  MemoryStorage,
+
+  // Viem helpers
+  createNodeWalletClient,
+
+  // Chain configs
+  campMainnet,
+  campTestnet,
+} from "@campnetwork/origin";
+```
+
+### Examples
+
+See the [examples/server-side](./examples/server-side) directory for complete Node.js examples including:
+
+- `connect-with-ethers.js` - Using ethers v6 Signer
+- `connect-with-viem.js` - Using viem WalletClient
+- `connect-with-custom-signer.js` - Custom signer implementation
+- `query-origin-data.js` - Querying blockchain data
+
 # React
 
 The React components and hooks can be imported as ES6 modules. The example below shows how to set up the `CampProvider` component and subsequently use the provided hooks and components.
@@ -519,7 +716,7 @@ createRoot(document.getElementById("root")).render(
 
 ## CampProvider
 
-The `CampProvider` component requires a `clientId` prop to be passed in order link the users to your app.
+The `CampProvider` component requires a `clientId` prop to be passed in order to link the users to your app.
 It can also take the following optional props:
 
 - `redirectUri` - `string | object` - Either a string that will be used as the redirect URI for all socials, or an object with the following optional properties: `twitter`, `spotify`. This is used to redirect the user to different pages after they have completed the OAuth flow for a social.
@@ -955,6 +1152,36 @@ When minting or updating an IpNFT, the following constraints apply to the `Licen
 - The royaltyBps must be between `1` and `10000` (0.01% to 100%).
 - The duration must be between `86400` seconds and `2628000` seconds (1 day to 30 days).
 
+### `createLicenseTerms(price, duration, royaltyBps, paymentToken)`
+
+A utility function to create properly validated license terms for minting and updating IpNFTs.
+
+- `price`: Price in wei (bigint)
+- `duration`: Duration in seconds (number)
+- `royaltyBps`: Royalty in basis points (number)
+- `paymentToken`: Payment token address (Address) - use `zeroAddress` from viem for native currency
+- **Returns:** A validated `LicenseTerms` object
+- **Throws:** Error if any parameter violates the constraints
+
+**Example:**
+
+```typescript
+import { createLicenseTerms } from "@campnetwork/origin";
+import { zeroAddress } from "viem";
+
+// Create license terms with validation
+const license = createLicenseTerms(
+  BigInt("1000000000000000"), // 0.001 CAMP in wei
+  86400, // 1 day in seconds
+  1000, // 10% royalty (1000 basis points)
+  zeroAddress // Native currency (CAMP)
+);
+
+// Use with minting functions
+await auth.origin.mintFile(file, metadata, license);
+await auth.origin.mintSocial("twitter", metadata, license);
+```
+
 ### File Upload & Minting
 
 #### `mintFile(file, metadata, license, parents?, options?)`