@native-engagement/sdk 0.9.0 → 0.10.0

package/package.json

@@ -1,23 +1,17 @@
 {
   "name": "@native-engagement/sdk",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "type": "module",
-  "description": "Authenticated remote TypeScript client for Native Engagement",
   "engines": {
     "node": ">=24.22.1 <25"
   },
-  "license": "UNLICENSED",
+  "license": "Apache-2.0",
   "files": [
     "dist",
-    "README.md",
+    "LICENSE",
     "release.json",
     "THIRD_PARTY_LICENSES.txt"
   ],
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/SENLIN746/native-engagement.git"
-  },
-  "homepage": "https://engagement.shipkitx.com/downloads",
   "publishConfig": {
     "access": "public",
     "tag": "beta"

package/release.json

@@ -1,8 +1,28 @@
 {
   "schemaVersion": 1,
-  "sourceCommit": "71e3baca49d33bfe86b38395fa0040b271f5e136",
+  "sourceCommit": "aafc75d7f07fce8c89000738fab3b8a4e3b37158",
   "channel": "beta",
   "bundledComponents": [
+    {
+      "name": "ajv",
+      "version": "8.20.0",
+      "license": "MIT"
+    },
+    {
+      "name": "fast-deep-equal",
+      "version": "3.1.3",
+      "license": "MIT"
+    },
+    {
+      "name": "json-schema-traverse",
+      "version": "1.0.0",
+      "license": "MIT"
+    },
+    {
+      "name": "fast-uri",
+      "version": "3.1.9",
+      "license": "BSD-3-Clause"
+    },
     {
       "name": "oauth4webapi",
       "version": "3.8.8",
@@ -14,5 +34,5 @@
       "license": "MIT"
     }
   ],
-  "lockSha256": "00164f8922c82350ad7cbe357f976d03b46faec9ebe48c634cb8ba2a922c3e3c"
+  "lockSha256": "1de45ef4132fe7e835a1edfaff8fcbc7fa1b6d64b1f2c5d3f865245311d0626d"
 }

package/README.md

@@ -1,141 +0,0 @@
-# Native Engagement SDK
-
-JavaScript and TypeScript access to Native Engagement. Requires Node.js 24.22.1+ in the 24 LTS line.
-
-```sh
-npm install @native-engagement/sdk@0.9.0
-```
-
-## Account and password sign-in
-
-The SDK supports browser-based account sign-in through OAuth Authorization Code with S256 PKCE. Enter your account, password and any MFA challenge on the identity service's browser page. The SDK receives a validated authorization result; your application does not collect the password.
-
-```js
-import { createNativePublicLogin, openNativeLoginPage,
-  RemoteNativeEngagementSdk, prospectClient } from '@native-engagement/sdk';
-
-const origin = 'https://engagement.shipkitx.com';
-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 prospects = prospectClient(sdk);
-```
-
-`openNativeLoginPage` opens the system browser on macOS, Windows and Linux. Applications with their own browser UI can supply an `async authorizationUrl => { ... }` callback instead. The browser callback must reach the Node.js process on its configured loopback address. Use a local Node.js process for this flow; a browser-only application should use the service's web login.
-
-Public configuration comes from `/releases/cli-login.json` on the exact HTTPS center, with pinned issuer, public client, resource and business scopes. Your administrator must provision your account and tenant permissions. Current directory and Profile grants govern every operation.
-
-Keep the short-lived grant in memory or your protected credential store. Sign in again after expiry; an active identity-service browser session can reuse SSO. The SDK does not automatically persist credentials. Sign out with `await login.revoke(grant)`. For automation, supply a separately authorized access token through a token provider or protected process environment. Password arguments and password-grant login are not offered.
-
-## Complete import, creation and association
-
-Country, industry, address, contact name/title and original score are optional `profile` strings. Source URLs are optional; supply the actual credential-free HTTP(S) source page when known. Source reference/version, observation time and current/historical status remain explicit. Persist and reuse the complete input and its idempotency key when retrying.
-
-```js
-const observedAt = new Date().toISOString();
-const input = {
-  idempotencyKey: 'research-november-v1', batchRef: 'research-november-v1', datasetRef: 'November research',
-  rows: [{
-    rowRef: 'row-1', sourceRef: 'reviewed-research-file', sourceVersion: 'v1',
-    selection: 'SELECTED', displayName: 'Example Company',
-    companyIdentity: { namespace: 'reviewed-company', value: 'company-001' },
-    profile: { observedAt, temporalStatus: 'CURRENT', country: 'CN', industry: 'Logistics',
-      address: 'Shanghai', contactName: 'Research Contact', contactTitle: 'Director', score: '8/10' },
-    contacts: [{ channel: 'EMAIL', value: 'research@example.test', observation: {
-      sourceRef: 'reviewed-research-file', sourceVersion: 'v1', observedAt,
-      temporalStatus: 'CURRENT', verificationStatus: 'PUBLIC_UNVERIFIED'
-    } }]
-  }]
-};
-const preview = await prospects.preview(input); // No business write.
-console.log(preview.rows); // Review HELD/REJECTED outcomes before importing.
-await prospects.import(input);
-const batch = await prospects.batch(input.batchRef);
-const imported = batch.rows.find(row => row.status === 'IMPORTED');
-if (!imported?.prospectRef) throw Error('Review the import receipt');
-const company = await prospects.company(imported.prospectRef);
-console.log(company.profileObservations, company.contacts);
-
-const route = company.contacts.find(item => item.channel === 'EMAIL');
-const source = route?.observations.find(item => item.temporalStatus === 'CURRENT');
-if (!route || !source) throw Error('A current imported email observation is required');
-const create = {
-  idempotencyKey: 'research-november-engagement-001', engagementRef: 'research-november-engagement-001',
-  prospectRef: company.prospectRef, contactRouteRef: route.contactRouteRef,
-  sourceRef: source.sourceRef, sourceVersion: source.sourceVersion, observedAt: source.observedAt,
-  whyFit: 'Reviewed logistics fit', whyNow: 'Reviewed current opportunity'
-};
-await prospects.createEngagement(create);
-const associated = await prospects.engagements(company.prospectRef, { limit: 20 });
-console.log(associated.entries); // Continue with associated.nextCursor when present.
-```
-
-Creation uses an exact imported CURRENT observation, current authorization and STOP policy. It records why-fit/why-now without sending or scheduling work. Changed source rows require a new version; names, emails and domains are not stable company identifiers. Score strings retain their original scale. Original research and verification belong to the archive/Knowledge owner; Native Engagement owns imported observations, provenance, receipts and engagement facts.
-
-## Bounded discovery and task tools
-
-`sdk.discoverContracts({query, kind, limit, cursor})` reads contract metadata without whole-library schemas. Use `sdk.schema(name, 'input')` or `'output'` for selected constraints. Existing `contracts()` and `schema(name)` keep their complete response defaults.
-
-The remote SDK exports `NativeMcpToolCatalog` and `MCP_CATALOG_META_KEY` for hosts that already own an authenticated MCP client:
-
-```js
-import { NativeMcpToolCatalog } from '@native-engagement/sdk';
-
-// 每个宿主任务独立管理定义；mcpClient 继续使用原 OAuth 会话。
-const catalog = new NativeMcpToolCatalog(mcpClient);
-await catalog.initialize();
-const tools = await catalog.load({task: 'prospect-import'});
-// 将 tools 注册为本任务的模型工具；它们保留原名称、输入约束和权限元数据。
-await registerTaskTools(tools);
-const result = await catalog.call('prospect.batch.preview', originalBatch);
-```
-
-Selections may specify `task`, capability `groups`, or exact tool `names`; a new selection replaces the previous set. `catalog.refresh()` preserves the explicit selection on stateless HTTPS. Plain `tools/list` refresh gets the server default. Hosts can use the MCP protocol directly without this helper. The helper caches static definitions, never authorization or business results. Full compatibility remains available through `{mode: 'full'}`.
-
-## Logged-in browser SOCIAL clients
-
-The development and prepared thin SDK entries export `browserSocialClient`, `browserSearchScope`, `browserAccountClient` and `browserPublicationLifecycle` for Douyin/TikTok browser transport. They require a matching center and an installed, observed platform module. Their presence does not establish platform availability in an existing published package or authorize a channel account.
-
-For existing private browser conversations, `browser.autonomy(key, options)` uses the original `social.autonomy.configure` contract. A current Human must provide the exact autonomy/control versions, delegate, expiry and reply limit. Without that bounded delegation, generated text remains a draft. `browserWorkerRoutes` and the existing routed Worker reuse Work/Invocation, account waits and durable original-operation positions; the `browserSocial` selection is retained across restart. Unread media and unmapped messages require Human inspection. Public task/notification Work, publication and media ports preserve their separate approvals and require observed platform configuration. This integration does not implement an Agent Runtime.
-
-The development SDK's `browserSocialRuntimeSkill()` returns the packaged Douyin/TikTok guide and its SHA-256 digest for an existing external Runtime/role. The original `xiaohongshuRuntimeSkill()` keeps its API and canonical guide. Both use the same distribution reader; reading instructions grants no tools or action authority. These local guidance readers are not part of the thin remote-client npm entry.
-
-```js
-import { browserSocialClient } from '@native-engagement/sdk';
-
-// selectedOwner contains the canonical engagementRef, conversationRef and profileRef.
-const browser = browserSocialClient(sdk, { ...selectedOwner, platform: 'TIKTOK' });
-const retained = await browser.get();
-const activity = await browser.activity(); // Retained state only; no browser action.
-// Request freshness only when the retained Source is insufficient for the task.
-const receipt = await browser.read(originalReadKey, {
-  view: 'CONTENT', pageLimit: 1, maxItems: 20, maxExpansions: 0, maxScrolls: 0
-});
-const operation = await browser.operation(receipt.entityRefs[0]);
-```
-
-Keep the original read key and dispatch when a response is lost. Poll the original operation and use its returned window; old retained content is not evidence of the latest search. Inbox/notification reads may change the platform's read markers. Backward history supplies context and does not trigger replies to old messages.
-
-`search` registers a public query view; `adoptTarget` selects a video or author from an exact Source fact/revision. `adoptDirect` accepts an account-owned inbox thread under current registration policy. Public authors and display names cannot supply private recipients. None of these calls submits content.
-
-`draft` freezes the exact Source, complete text and `browserIntent`. `PUBLISH` also freezes video/cover Asset manifests, visibility, declarations and schedule/time zone. Queueing requires the actual current Human review; this client grants no autonomy. Preserve the original request after submission. Use `verify` for an uncertain effect; `authorizeRecovery` requires current Human review after a same-account machine update and permits original verification only. Account pause recovery uses the exact retained activity revision and preserves budgets.
-
-`browserPublicationLifecycle(message, operation, retainedView)` projects retained processing/review/schedule observations and the original approved time without browsing or dispatching. `CLIENT_VISIBLE` does not attest public delivery. Rejection, platform cancellation or a settings mismatch requires review of the original business request. `scheduleCancelDraft` and `scheduleRescheduleDraft` create separately reviewed management drafts for an exact current own scheduled POST; they do not alter the original publication request. Local `cancel` only cancels an undispatched QUEUED request. A lost management response continues with its original `verify`, never another submit.
-
-## Batch pagination
-
-Each response has at most 100 entries; total history has no 100-batch cap. Concurrent imports can shift offset pages; restart from the first page when refreshing. Associated engagements use a separate signed cursor.
-
-```js
-let offset = 0;
-for (;;) {
-  const page = await prospects.batches({ offset, limit: 20 });
-  console.log(page.total, page.entries);
-  if (page.nextOffset === null) break;
-  offset = page.nextOffset;
-}
-```
-
-Exports include `RemoteNativeEngagementSdk`, `RemoteNativeEngagementError`, `prospectClient`, `createNativePublicLogin`, `openNativeLoginPage`, `NativePublicLogin`, `NativeLoginConfiguration`, `NativeLoginGrant`, `RemoteSdkOptions` and Prospect DTOs. Generic `contracts`, `schema`, `query` and `command` remain available. Commands require a stable idempotency key. Unknown external effects require original-operation inspection.
-
-This beta uses license `UNLICENSED`. [Sign-in and MCP OAuth guide](https://engagement.shipkitx.com/releases/authentication.md) · [Downloads](https://engagement.shipkitx.com/downloads)