@native-engagement/sdk 0.10.0 → 0.11.0

package/README.md

@@ -0,0 +1,54 @@
+# Native Engagement SDK
+
+JavaScript and TypeScript access to Native Engagement. Requires Node.js 24.22.1 or later in the Node.js 24 line.
+
+```sh
+npm install @native-engagement/sdk@0.11.0
+```
+
+## Connect and sign in
+
+Use the trusted service URL supplied by your administrator. Browser sign-in handles account credentials and any MFA challenge.
+
+```js
+import {
+  createNativePublicLogin, openNativeLoginPage, RemoteNativeEngagementSdk
+} from '@native-engagement/sdk';
+
+const origin = 'https://engagement.example';
+const login = await createNativePublicLogin(origin);
+const grant = await login.authorize(AbortSignal.timeout(180_000), openNativeLoginPage);
+const sdk = new RemoteNativeEngagementSdk({
+  baseUrl: origin,
+  accessToken: () => grant.accessToken
+});
+
+const discovery = await sdk.discoverContracts({ query: 'execution.device', limit: 10 });
+console.log(discovery);
+// At the end of the session:
+await login.revoke(grant);
+```
+
+Your administrator provisions account and tenant permissions. Each operation checks current authorization. Keep grants in memory or an approved protected credential store. For an existing automation identity, supply its authorized token provider through `accessToken`; never put credentials in command arguments or source code.
+
+## Discover and call capabilities
+
+Use `sdk.discoverContracts({query, kind, limit, cursor})` to find relevant capabilities and `sdk.schema(name, 'input')` for their current input constraints. Call `sdk.query({name, payload})` or `sdk.command({name, payload})` with those inputs. Commands require a stable `idempotencyKey`.
+
+The SDK also exports typed helpers for supported business operations and `NativeMcpToolCatalog` for a host that already owns an authenticated MCP client. Capability discovery grants no additional permissions.
+
+Keep original request keys and receipts. After a lost response or an unknown external result, inspect the original operation before retrying. Request acceptance, operation completion and external delivery are separate outcomes.
+
+## Prepare an execution environment
+
+This package is a remote client. It does not contain another Agent Runtime, an execution node, channel applications or models. Your Agent Runtime remains managed by its existing host.
+
+`installationRuntimeSkill()` returns offline execution prerequisites and dependency reuse guidance. Discover `execution.device.list` and `execution.device.inspect` to reuse an existing authorized environment. When another environment is needed, follow `execution.environment.request` and its original authenticated installation handoff.
+
+The host Agent can prepare selected authorized dependencies and install a trusted execution artifact. Reuse compatible installed programs and caches. An execution artifact supplies the local Node/Worker programs; an existing installation can continue to use its original programs. A Desktop application is optional.
+
+Installation, account pairing, channel authorization and updates retain their own checks. Preserve installation identity, credentials, task journals and recovery state across upgrades. Missing trusted artifacts or unsupported platforms must remain explicit.
+
+## License
+
+Apache-2.0. Bundled third-party notices are included in `THIRD_PARTY_LICENSES.txt`.