@bizjaya/finclient 0.1.1 → 0.2.1

package/README.md

@@ -1,6 +1,7 @@
 # @bizjaya/finclient
 
-The official TypeScript SDK for FinCopy's public `/v1` API. It supports Node.js 18 and later, with ESM and CommonJS builds.
+The official TypeScript SDK for FinCopy's public API, `https://api.fincopy.io`. Since version 0.2.0 it uses numeric ACNO
+account paths under `/v1/fxs`, which changed the 0.1 API; see the changelog before upgrading.
 
 ```sh
 npm install @bizjaya/finclient
@@ -11,33 +12,67 @@ import { FinClient } from "@bizjaya/finclient";
 
 const fin = new FinClient({ apiKey: process.env.FINCOPY_API_KEY! });
 const accounts = await fin.copy.accounts.list();
-for (const account of accounts) console.log(account.Fleet?.Account?.Id, account.Fleet?.Account?.Login);
-
-// Read what changed since the saved cursor, one page at a time; save the cursor after each page.
-let cursor: string | undefined = loadSavedCursor();
-for await (const page of fin.copy.changes.readPages(cursor)) {
-  for (const change of page.Changes ?? []) console.log(change.Entity, change.AccountId, change.OID, change.Status);
-  if (page.Cursor) saveCursor(page.Cursor);
-}
+for (const account of accounts.items) console.log(account.Fleet?.Account?.ACNO, account.Fleet?.Account?.Login);
+
+// ACNO is in the route; the JSON body contains only trade fields.
+// await fin.copy.orders.make(52014125, { SYM: "EURUSD", ACT: "NEW", OTY: "OP_BUY", LOT: 0.01 });
+```
+
+The client defaults to `https://api.fincopy.io`. Account-scoped methods take the numeric ACNO, and paged list methods
+return `{ items, paging, ... }`. DTO fields keep the API's PascalCase names.
+
+- `copy.accounts`: settings and lifecycle, pairs, symbols, quotes, orders, history, DCA, performance, activity, strategy
+  preview and apply, and terminal operations.
+- `copy.orders`: preflight, trade, hedge, modify, cancel and DCA answers.
+- `copy.fx`: lists across every account you can reach (pairs, orders, history, activity, DCA, terminal operations,
+  performance window and bars), strategies, signals, alerts, brokers and the event stream.
+- `copy.changes` and `copy.webhooks`: the change feed and webhook setup.
+
+## API key or member session
+
+API-key mode is for trusted server-side code. Do not put an API key in browser JavaScript, a mobile app, a public
+repository, or a client-side environment variable.
+
+Member session mode sends the signed-in member's `fincopy_member` cookie instead of a key: omit `apiKey` and pass `fetch`.
+A session client defaults to `credentials: "include"`, so in a browser page on a FinCopy site the browser's `fetch` sends
+the cookie. On a server, pass a `fetch` that adds the cookie header.
+
+```ts
+const fin = new FinClient({ fetch: (input, init) => fetch(input, init) });
+const account = await fin.copy.accounts.get(52014125);
 ```
 
-`loadSavedCursor` and `saveCursor` stand for your own storage. The first call without a cursor starts at "now".
+The API accepts browser requests only from FinCopy's own sites. Session trade writes pass the member's trade-PIN gate on
+the server. The main entry uses no Node.js built-ins, so it runs in browsers, Node.js 20+, Deno and Bun.
+
+`copy.accounts.remove(acno, { TrPin }, options)` disconnects the hosted terminal, forgets its broker password and frees its seat.
+Customer account settings and trade history remain so the login can be restored later; a free demo's account and terminal records
+are deleted. Open orders stay at the broker, and virtual TP, SL and TS stop working while no terminal runs. Include the member's
+trading PIN for a session account when its PIN is enabled; API-key requests do not use a session PIN. Pass an `idempotencyKey`
+in `options` so retries receive the same operation.
+
+## Results, errors and the stream
+
+Trade calls report that an operation was queued; follow the stream, change feed or webhook for its terminal result. Errors
+are raised as `FinApiError` with HTTP status, API code, validation errors, any `Retry-After` value, and an `errorCode` of
+`timeout`, `network`, `rate_limited`, `invalid_response` or `empty_response` when the SDK set one. Retries reuse the same
+`Idempotency-Key`.
 
-A failed call throws `FinApiError` with `statusCode`, FinCopy's `code`, `errors`, and, when the SDK set it, `errorCode`
-(`timeout`, `network`, `rate_limited`, `invalid_response` or `empty_response`) and `retryAfterMs`. Calls are retried on
-rate limits, gateway errors and network failures, honouring the API's `Retry-After`.
+`copy.fx.stream()` does not reconnect. It ends when the server closes it (about every 30 minutes); a broken connection
+raises a `network` error. Open it again in a loop, waiting a few seconds between attempts.
 
-The client is server-side only. Do not put an API key in browser JavaScript, a mobile application, a public repository, or a
-client-side environment variable. FinCopy's envelope is handled by the client; DTO fields keep the API's PascalCase wire names.
-Writes automatically carry an `Idempotency-Key`, which can be supplied explicitly in the request options when a caller needs
-to retry the same operation later. Orders complete asynchronously; use the change feed or webhook to learn their result.
+## Webhooks
 
-The API key grants the permissions assigned to that key. Store it as a server secret and give it only the permissions the
-application needs.
+Webhook verification is server-side and uses Node.js's crypto module, so it has its own entry:
+
+```ts
+import { FinWebhook } from "@bizjaya/finclient/webhook";
+
+const valid = FinWebhook.verify(secret, timestampHeader, rawBody, signatureHeader);
+```
 
-See [FinCopy API docs](https://fincopy.io/docs) and the [FinClient source](https://github.com/bizjaya/FinClient). The
-[QuickStart](./examples/QuickStart.ts) example lists accounts and reads the change feed; its order call is commented out
-because it places a trade.
+See the [FinCopy API docs](https://fincopy.io/docs), the [QuickStart](./examples/QuickStart.ts), and the
+[FinClient source](https://github.com/bizjaya/FinClient).
 
 ## Build from source