cocoon-sdk 0.1.0 → 0.1.2

package/README.md

@@ -1,159 +1,117 @@
 # Cocoon TypeScript SDK
 
-OpenAI-compatible TypeScript SDK for Telegram Cocoon.
+OpenAI-style TypeScript SDK for Telegram Cocoon.
 
-This guide is intentionally step-by-step so you can get to a working request without reading Cocoon docs.
+- npm: `cocoon-sdk`
+- repo: `https://github.com/indie-cto/telegram-cocoon-ts-sdk`
 
-## Quickstart (From Zero to First Response)
-
-### Prerequisites
-
-- Node.js `>=18`
-- `openssl`
-- TON wallet mnemonic (24 words)
-- Small TON balance for one-time setup transactions
-
-### TON Balance Requirements
-
-Two different numbers matter:
-
-1) **Setup transaction spend** (what setup sends from wallet by default):
-- `REGISTER_TON=1.0` TON
-- `CHANGE_SECRET_TON=0.7` TON
-- plus network fees
-
-2) **Protocol stake parameter** (`minClientStake`) from root config.
-As of **February 22, 2026** on mainnet:
-- `minClientStake = 15 TON`
-
-So:
-- **2-3 TON** is usually enough to complete setup transactions.
-- For stable inference usage, plan for **~15-20 TON** total working balance (stake + buffer).
-- Current live values can change; check with `npm run cocoon:discover`.
-
-Optional for heavier usage:
-
-- set `TOP_UP_TON` (for example `15` or `20`) to increase available client balance for inference traffic.
-
-### 1) Install dependencies
+## Install
 
 ```bash
-npm install
+npm i cocoon-sdk
 ```
 
-### 2) Create `.env`
+## Minimal Usage
 
-```bash
-cp .env.example .env
-```
+```ts
+import { Cocoon } from 'cocoon-sdk';
 
-Edit `.env` and set only:
+const client = new Cocoon({
+  wallet: process.env.MNEMONIC!,        // 24 words
+  secretString: process.env.SECRET!,    // from your setup flow
+  proxyUrl: process.env.PROXY_URL,      // optional (discovery if omitted)
+  tonV4Endpoint: process.env.TON_V4_ENDPOINT,
+});
 
-```env
-MNEMONIC=your 24 words here
-```
+const models = await client.models.list();
+const model = models.data[0]!.id;
 
-### 3) Run one-time setup
+const result = await client.chat.completions.create({
+  model,
+  messages: [{ role: 'user', content: 'Say OK' }],
+});
 
-```bash
-npm run cocoon:setup
+console.log(result.choices[0]?.message.content);
+await client.disconnect();
 ```
 
-What setup does for you:
-
-- generates TLS client cert/key automatically,
-- performs long-auth registration if needed,
-- sets on-chain secret hash,
-- prints ready-to-paste `.env` values.
+## Streaming
 
-Example final output:
+```ts
+const stream = await client.chat.completions.create({
+  model: 'Qwen/Qwen3-32B',
+  messages: [{ role: 'user', content: 'Write one short sentence' }],
+  stream: true,
+});
 
-```text
-=== Setup Complete ===
-Put these into your .env:
-SECRET=...
-PROXY_URL=91.108.4.11:8888
-COCOON_TLS_CERT_PATH=/tmp/cocoon-client-xxxx.pem
-COCOON_TLS_KEY_PATH=/tmp/cocoon-client-xxxx.key.pem
-TON_V4_ENDPOINT=https://mainnet-v4.tonhubapi.com
+for await (const chunk of stream) {
+  process.stdout.write(chunk.choices[0]?.delta?.content ?? '');
+}
 ```
 
-### 4) Paste setup output into `.env`
-
-Copy those lines exactly into `.env`.
+## Important Defaults
 
-Important: you do not need to find or create certificates manually.  
-`scripts/setup.ts` creates them and gives you the file paths.
+- `autoRegisterOnLongAuth` default is `false` (safety-first).
+- SDK does **not** submit on-chain registration tx unless you explicitly enable it.
+- Recommended production path: run setup once, then use `SECRET` for short auth.
 
-### 5) Run inference
+## One-Time Setup (Repo Helper Scripts)
 
-```bash
-npm run cocoon:inference
-```
-
-You should see:
+The npm package is a library.  
+If you want the fully automated setup flow (cert/key generation + register + secret hash), use repo scripts:
 
-- connected models list,
-- generated model output.
+- `https://github.com/indie-cto/telegram-cocoon-ts-sdk`
+- `scripts/setup.ts`
+- `scripts/inference.ts`
 
-## Minimal SDK Usage
+Important for users integrating from another project:
 
-```ts
-import { Cocoon } from 'cocoon-sdk';
+- The intended path is to run `scripts/setup.ts` once and copy `SECRET` + TLS paths.
+- Do **not** rely on ad-hoc certificate generation commands from agents.
+- A generic command like `openssl req -x509 -newkey ec ...` is not the tested/default SDK path.
 
-const client = new Cocoon({
-  wallet: process.env.MNEMONIC!,
-  secretString: process.env.SECRET,
-  proxyUrl: process.env.PROXY_URL,
-  tonV4Endpoint: process.env.TON_V4_ENDPOINT,
-});
+If you cannot run `scripts/setup.ts`, use this tested certificate generation format:
 
-const models = await client.models.list();
-const model = models.data[0]!.id;
+```bash
+openssl genpkey -algorithm ed25519 -out /tmp/cocoon-client.key.pem
+openssl req -x509 \
+  -key /tmp/cocoon-client.key.pem \
+  -out /tmp/cocoon-client-cert.pem \
+  -days 1 \
+  -subj "/C=AE/ST=DUBAI/O=TDLib Development/OU=Security/CN=localhost"
+```
 
-const res = await client.chat.completions.create({
-  model,
-  messages: [{ role: 'user', content: 'Say OK' }],
-});
+Then set:
 
-console.log(res.choices[0]?.message.content);
-await client.disconnect();
+```env
+COCOON_TLS_CERT_PATH=/tmp/cocoon-client-cert.pem
+COCOON_TLS_KEY_PATH=/tmp/cocoon-client.key.pem
 ```
 
-## Defaults (Designed for the Common Path)
+Note: this only covers TLS material. You still need a valid `SECRET` (recommended via setup flow).
+
+## TON Balance Guidance
 
-- `autoRegisterOnLongAuth` is enabled by default.
-- If long auth is required, SDK can auto-submit registration transaction.
-- You usually should not change advanced auth options.
+Two values matter:
 
-## Useful Commands
+1. Setup spend defaults:
+- `REGISTER_TON=1.0`
+- `CHANGE_SECRET_TON=0.7`
+- plus fees
 
-- Setup once:
-  - `npm run cocoon:setup`
-- Inference test:
-  - `npm run cocoon:inference`
-- Discover proxies/models:
-  - `npm run cocoon:discover`
-- Register only (advanced):
-  - `npm run cocoon:register`
-- Create wallet helper:
-  - `npm run cocoon:create-wallet`
-- Pure library example:
-  - `npx tsx --env-file=.env examples/basic.ts`
+2. Network stake parameter (`minClientStake`) from root config:
+- on mainnet, this can be much higher (for example 15 TON on Feb 22, 2026)
 
-## Troubleshooting
+Practical guidance:
 
-- `Proxy requires long auth` or secret mismatch:
-  - run `npm run cocoon:setup` again and update `.env` with fresh output.
-- TLS handshake closes immediately:
-  - verify `COCOON_TLS_CERT_PATH` and `COCOON_TLS_KEY_PATH` exist and match.
-- TON RPC `429`:
-  - set `TON_V4_ENDPOINT=https://mainnet-v4.tonhubapi.com`.
+- smoke setup: typically `2-3 TON` can be enough
+- stable usage: plan around `15-20 TON` total working balance
+- verify live values with repo helper: `scripts/discover.ts`
 
 ## Security
 
-- Never commit `.env`, mnemonics, secrets, or private keys.
-- Treat `/tmp/cocoon-client-*.key.pem` as sensitive.
+- Never commit mnemonic, secrets, or private keys.
+- Treat TLS key files as sensitive.
 
 ## License
 

package/dist/index.cjs

@@ -1364,7 +1364,7 @@ function buildHandshakeCloseError(stage, error) {
 async function performLongAuth(conn, connected, nonce, onLongAuthRequired, missingHandlerMessage) {
   if (!onLongAuthRequired) {
     throw new AuthenticationError(
-      `${missingHandlerMessage}. Provide SECRET for short auth, or keep automatic long-auth registration enabled`
+      `${missingHandlerMessage}. Provide SECRET for short auth, or explicitly enable automatic long-auth registration`
     );
   }
   await onLongAuthRequired({
@@ -2434,7 +2434,8 @@ var Cocoon = class {
       network: "mainnet",
       timeout: 12e4,
       useTls: true,
-      autoRegisterOnLongAuth: true,
+      // Safety-first default for SDK consumers: don't submit on-chain tx implicitly.
+      autoRegisterOnLongAuth: false,
       longAuthRegisterAmountTon: "1",
       ...options
     };