@native-marketing/sdk 0.0.0-stage → 0.1.1

package/README.md

@@ -1,3 +1,40 @@
-# Temporary Holding Version
+# @native-marketing/sdk
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Node.js 24 authenticated clients for Native Marketing. No database access, server installation, planner or Runtime.
+
+```sh
+npm install @native-marketing/sdk
+```
+
+```ts
+import { withNativeAgentClient, NativeAgentClientError } from '@native-marketing/sdk';
+
+const resource = process.env.CF_AGENT_RESOURCE;
+const accessToken = process.env.CF_AGENT_ACCESS_TOKEN;
+if (!resource || !accessToken) throw new Error('Configure resource-bound OAuth credentials');
+
+await withNativeAgentClient({ resource, accessToken }, async (native) => {
+  const page = await native.findCapabilities({ query: '保存研究结论' });
+  console.log(page);
+});
+```
+
+The server filters discovery using current object, OAuth scopes and business permissions. Read one exact capability definition before constructing its input. Search saved business content with `searchBusiness`; use `getBusinessSummary` for a bounded summary and nextActions. The caller decides whether to continue. Ordinary collaboration and explicitly assigned execution remain separate.
+
+Writes retain exact schema fingerprints, request IDs, human decisions and optimistic concurrency. On `NativeAgentClientError` inspect `code`, `outcome` and `details`. An UNKNOWN outcome is not a rollback: follow the returned original receipt lookup using the same resource and current authorization. Never automatically retry writes, replace the request ID or infer success from the latest document. Refresh current business content separately after recovering the original result.
+
+Credentials belong in a protected credential store, never model prompts or arguments. This package does not acquire or widen permissions on import. Node.js 24 is required by the MCP client.
+
+## HTTP client
+
+```ts
+import { createContentFactoryClient } from '@native-marketing/sdk/http';
+
+const native = createContentFactoryClient({ baseUrl: 'https://ip.shipkitx.com/api/v1' });
+// A browser uses its existing authorized session. Node callers must provide an
+// authenticated fetch implementation; a base URL alone does not authenticate.
+```
+
+The `/http` entry contains the existing typed HTTP client, validators and generated endpoint types; it does not import the Node MCP/CLI implementation. It does not retry writes or manage browser sessions for Node callers.
+
+The package's `release.json` records the actual source commit and generated API-types hash. This is a local build receipt, not CI provenance or proof that every remote business journey has been accepted. Rights reserved; public package availability does not grant an open-source license (UNLICENSED).