@native-knowledge/knowledge-sdk 0.0.0-stage → 0.1.0-rc.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 native-knowledge contributors
+
+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

@@ -1,3 +1,47 @@
-# Temporary Holding Version
+# native-knowledge 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+ ESM clients for native-knowledge. MIT licensed.
+
+```sh
+npm install @native-knowledge/knowledge-sdk@next
+```
+
+```ts
+import {KnowledgeAgentClient} from '@native-knowledge/knowledge-sdk';
+
+const client = new KnowledgeAgentClient({
+  baseUrl: 'https://knowledge.example.com',
+  expectedTenantId: 'your-tenant-id',
+  token: process.env.KNOWLEDGE_V2_OAUTH_ACCESS_TOKEN!,
+});
+const result = await client.discover({query: 'saved materials'});
+```
+
+Use `execute(tool, input)` only after explicitly choosing an operation.
+Guidance and `nextActions` never grant permission or execute themselves.
+Writes are attempted once. After cancellation or a lost response, inspect the
+exact receipt/state before deciding what to do; do not automatically replay writes.
+
+HTTPS is required by default. `allowInsecureHttp: true` explicitly permits HTTP
+for a trusted local test server. Never put tokens in a URL or command-line flag.
+Provider-discovered credential endpoints must remain on the configured origin;
+redirects are refused.
+
+All clients default to a 30-second request/body deadline. `timeoutMs` can be
+1–300000. Buffered JSON defaults to 512 KiB (`maxJsonBytes`, maximum 16 MiB),
+and buffered file reads default to 16 MiB (`maxContentBytes`, maximum 256 MiB).
+Streams use backpressure and the deadline without buffering entire files.
+Methods supporting an `AbortSignal` preserve caller cancellation.
+
+`KnowledgeResourceClient.read()` verifies exact refs, canonical Base64, lengths
+and SHA-256. A legacy Reference record digest is distinct from the file hash.
+Resource streams and `KnowledgeAgentClient.openMaterialStream()` require a server
+supporting explicit `x-knowledge-resource-transfer: context-v1` response binding.
+An older server that omits the binding is refused before exposing stream bytes;
+ordinary versioned JSON APIs remain available. The server checks live authority
+during transfer. `SERVER_VERIFIED_BEFORE_HEADERS` describes server verification;
+it is not a client-computed hash of an entire or partial stream.
+
+The package includes its client contracts. It requires no private workspace
+packages and contains no local Host administration or collector runtime.
+It neither starts services nor enables collection when installed or imported.