@zebec-network/zebec-stream-sdk 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Zebec Protocol
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,354 @@
+# Zebec Stream SDK
+
+A TypeScript SDK for interacting with the Zebec Stream protocol on Solana. This SDK provides a comprehensive interface for creating, managing, and interacting with payment streams on the Zebec Network.
+
+## Features
+
+- **Stream Management**: Create, cancel, pause, and resume payment streams
+- **Token Streaming**: Support for SPL token streaming with customizable parameters
+- **Admin Functions**: Configuration management and token whitelisting
+- **Flexible Permissions**: Granular control over stream permissions and capabilities
+- **Type Safety**: Full TypeScript support with comprehensive type definitions
+
+## Installation
+
+```bash
+npm install @zebec-network/stream-sdk
+```
+
+```bash
+yarn add @zebec-network/stream-sdk
+```
+
+## Quick Start
+
+### Setting up the Service
+
+```typescript
+import { Connection, PublicKey } from "@solana/web3.js";
+import { ZebecStreamService, createAnchorProvider } from "@zebec-network/stream-sdk";
+
+// Create connection
+const connection = new Connection("https://api.devnet.solana.com");
+
+// Create provider with your wallet
+const provider = createAnchorProvider(connection, wallet);
+
+// Initialize the service
+const streamService = ZebecStreamService.create(provider, "devnet");
+```
+
+### Creating a Stream
+
+```typescript
+const streamParams = {
+  receiver: "ReceiverPublicKeyHere",
+  sender: "SenderPublicKeyHere", 
+  streamToken: "TokenMintAddressHere",
+  amount: "1000", // Amount in token units
+  duration: 86400, // 1 day in seconds
+  streamFrequency: 3600, // 1 hour in seconds
+  streamName: "Monthly Salary",
+  startNow: true,
+  automaticWithdrawal: false,
+  cancelableByRecipient: true,
+  cancelableBySender: true,
+  isPausable: true,
+  transferableByRecipient: false,
+  transferableBySender: false,
+  canTopup: true,
+  rateUpdatable: false,
+  cliffPercentage: 0, // No cliff
+  startTime: Math.floor(Date.now() / 1000)
+};
+
+const transaction = await streamService.createStream(streamParams);
+const signature = await transaction.execute();
+```
+
+## API Reference
+
+### ZebecStreamService
+
+The main service class for interacting with Zebec streams.
+
+#### Constructor
+
+```typescript
+static create(provider: Provider, network: "mainnet-beta" | "devnet"): ZebecStreamService
+```
+
+### Stream Operations
+
+#### createStream(params: CreateStreamParams)
+
+Creates a new payment stream.
+
+**Parameters:**
+
+- `receiver`: Address - The recipient's public key
+- `sender`: Address - The sender's public key  
+- `streamToken`: Address - The SPL token mint address
+- `amount`: Numeric - Amount to stream (in token units)
+- `duration`: number - Stream duration in seconds
+- `streamFrequency`: number - Withdrawal frequency in seconds
+- `streamName`: string - Human-readable stream name
+- `startNow`: boolean - Whether to start immediately
+- `startTime`: number - Unix timestamp for stream start
+- `cliffPercentage`: Numeric - Percentage locked until cliff period
+- `automaticWithdrawal`: boolean - Enable automatic withdrawals
+- `cancelableByRecipient`: boolean - Allow recipient to cancel
+- `cancelableBySender`: boolean - Allow sender to cancel
+- `isPausable`: boolean - Allow stream pausing
+- `transferableByRecipient`: boolean - Allow recipient to transfer
+- `transferableBySender`: boolean - Allow sender to transfer
+- `canTopup`: boolean - Allow adding funds to stream
+- `rateUpdatable`: boolean - Allow rate modifications
+- `feePayer?`: Address - Optional custom fee payer
+- `streamMetadataKeypair?`: Keypair - Optional custom metadata keypair
+
+#### cancelStream(params: CancelStreamParams)
+
+Cancels an existing stream.
+
+**Parameters:**
+
+- `streamMetadata`: Address - The stream metadata account address
+- `user`: Address - The user canceling the stream (sender or receiver)
+- `feePayer?`: Address - Optional custom fee payer
+
+#### pauseResumeStream(params: PauseResumeStreamParams)
+
+Pauses or resumes a stream.
+
+**Parameters:**
+
+- `streamMetadata`: Address - The stream metadata account address
+
+#### withdrawStream(params: WithdrawStreamParams)
+
+Withdraws available tokens from a stream.
+
+**Parameters:**
+
+- `streamMetadata`: Address - The stream metadata account address
+- `receiver`: Address - The recipient's address
+- `withdrawer?`: Address - Optional custom withdrawer (defaults to receiver)
+
+#### changeStreamReceiver(params: ChangeStreamReceiverParams)
+
+Changes the recipient of a stream.
+
+**Parameters:**
+
+- `streamMetadata`: Address - The stream metadata account address
+- `newRecipient`: Address - The new recipient's address
+- `signer`: Address - The current authorized signer
+
+### Information Retrieval
+
+#### getStreamMetadataInfo(streamMetadata: Address, commitment?: Commitment)
+
+Retrieves detailed information about a stream.
+
+**Returns:** `StreamMetadataInfo` containing:
+
+- `parties`: Sender and receiver addresses
+- `financials`: Token info, amounts, and cliff percentage
+- `schedule`: Timing information and status
+- `permissions`: Stream permission settings
+- `streamName`: The stream's name
+
+#### getStreamConfigInfo(commitment?: Commitment)
+
+Retrieves global stream configuration.
+
+**Returns:** `StreamConfigInfo` containing:
+
+- `admin`: Admin public key
+- `withdrawerAccount`: Withdraw account address
+- `whitelistedTokens`: Array of whitelisted token addresses
+- `platformFee`: Platform fee percentage
+- `baseFee`: Base fee percentage  
+- `frequencies`: Allowed stream frequencies
+
+### Admin Operations
+
+#### initializeConfig(params: InitializeConfigParams)
+
+Initializes the global stream configuration (admin only).
+
+**Parameters:**
+
+- `admin?`: Address - Admin address (defaults to provider wallet)
+- `config.baseFeePercent`: Numeric - Base fee percentage
+- `config.platformFeePercent`: Numeric - Platform fee percentage
+- `config.frequencies`: number[] - Allowed stream frequencies
+- `config.withdrawAccount`: Address - Platform withdraw account
+
+#### whiteListTokens(params: WhiteListTokensParams)
+
+Adds tokens to the whitelist (admin only).
+
+**Parameters:**
+
+- `admin`: Address - Admin address
+- `tokens`: Address[] - Array of token mint addresses to whitelist
+
+## Types
+
+### StreamMetadataInfo
+
+```typescript
+type StreamMetadataInfo = {
+  parties: {
+    sender: PublicKey;
+    receiver: PublicKey;
+  };
+  financials: {
+    streamToken: PublicKey;
+    cliffPercentage: number;
+    depositedAmount: string;
+    withdrawnAmount: string;
+  };
+  schedule: {
+    startTime: number;
+    endTime: number;
+    lastWithdrawTime: number;
+    frequency: number;
+    duration: number;
+    pausedTimestamp: number;
+    pausedInterval: number;
+    canceledTimestamp: number;
+  };
+  permissions: {
+    cancelableBySender: boolean;
+    cancelableByRecipient: boolean;
+    automaticWithdrawal: boolean;
+    transferableBySender: boolean;
+    transferableByRecipient: boolean;
+    canTopup: boolean;
+    isPausable: boolean;
+    rateUpdatable: boolean;
+  };
+  streamName: string;
+};
+```
+
+### StreamConfigInfo
+
+```typescript
+type StreamConfigInfo = {
+  admin: PublicKey;
+  withdrawerAccount: PublicKey;
+  whitelistedTokens: PublicKey[];
+  platformFee: number;
+  baseFee: number;
+  frequencies: number[];
+};
+```
+
+## Provider Setup
+
+### AnchorProvider (Read/Write Operations)
+
+For operations that require signing transactions:
+
+```typescript
+import { createAnchorProvider } from "@zebec-network/stream-sdk";
+
+const provider = createAnchorProvider(connection, wallet, {
+  commitment: "confirmed",
+  preflightCommitment: "confirmed"
+});
+```
+
+### ReadonlyProvider (Read-Only Operations)
+
+For read-only operations:
+
+```typescript
+import { createReadonlyProvider } from "@zebec-network/stream-sdk";
+
+const provider = createReadonlyProvider(connection, optionalWalletAddress);
+```
+
+## Examples
+
+### Complete Stream Lifecycle
+
+```typescript
+// 1. Create a stream
+const createParams = {
+  receiver: receiverAddress,
+  sender: senderAddress,
+  streamToken: tokenMintAddress,
+  amount: "1000",
+  duration: 86400, // 1 day
+  streamFrequency: 3600, // 1 hour
+  streamName: "Test Stream",
+  startNow: true,
+  // ... other parameters
+};
+
+const createTx = await streamService.createStream(createParams);
+await createTx.execute();
+
+// 2. Get stream info
+const streamInfo = await streamService.getStreamMetadataInfo(streamMetadata);
+console.log("Stream info:", streamInfo);
+
+// 3. Withdraw from stream
+const withdrawTx = await streamService.withdrawStream({
+  streamMetadata,
+  receiver: receiverAddress
+});
+await withdrawTx.execute();
+
+// 4. Cancel stream
+const cancelTx = await streamService.cancelStream({
+  streamMetadata,
+  user: senderAddress
+});
+await cancelTx.execute();
+```
+
+### Error Handling
+
+```typescript
+try {
+  const transaction = await streamService.createStream(params);
+  const signature = await transaction.execute();
+  console.log("Stream created:", signature);
+} catch (error) {
+  if (error.message.includes("Invalid stream frequency")) {
+    console.error("Please use an allowed stream frequency");
+  } else {
+    console.error("Stream creation failed:", error);
+  }
+}
+```
+
+## Network Support
+
+- **Mainnet Beta**: Production environment
+- **Devnet**: Development and testing environment
+- **Testnet**: Not supported
+
+## Dependencies
+
+- `@coral-xyz/anchor`: Anchor framework for Solana
+- `@solana/web3.js`: Solana Web3 JavaScript API
+- `@zebec-network/core-utils`: Zebec utility functions
+- `@zebec-network/solana-common`: Common Solana utilities
+- `bignumber.js`: Arbitrary precision arithmetic
+
+## License
+
+This project is licensed under the MIT License.
+
+## Support
+
+For issues and questions:
+
+- GitHub Issues: [Repository Issues](https://github.com/zebec-network/stream-sdk/issues)

package/dist/artifacts/index.d.ts

@@ -0,0 +1,3 @@
+import { ZebecStream as ZebecStreamIdl } from "./zebec_stream";
+declare const ZEBEC_STREAM_IDL: ZebecStreamIdl;
+export { ZEBEC_STREAM_IDL, ZebecStreamIdl };

package/dist/artifacts/index.js

@@ -0,0 +1,9 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ZEBEC_STREAM_IDL = void 0;
+const zebec_stream_json_1 = __importDefault(require("./zebec_stream.json"));
+const ZEBEC_STREAM_IDL = zebec_stream_json_1.default;
+exports.ZEBEC_STREAM_IDL = ZEBEC_STREAM_IDL;