@native-engagement/sdk 0.0.0-stage → 0.8.0

package/README.md

@@ -1,3 +1,25 @@
-# Temporary Holding Version
+# Native Engagement 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.
+Authenticated JavaScript and TypeScript access to Native Engagement's canonical HTTPS contracts. Requires Node.js 24.22.1 or newer in the 24 LTS line. This package contains the remote client; local execution, desktop processes and channel credentials remain with their authorized owners.
+
+```sh
+npm install @native-engagement/sdk@beta
+```
+
+```js
+import { RemoteNativeEngagementSdk } from '@native-engagement/sdk';
+
+const client = new RemoteNativeEngagementSdk({
+  baseUrl: 'https://engagement.shipkitx.com',
+  accessToken: () => process.env.NATIVE_ENGAGEMENT_BEARER_TOKEN ?? ''
+});
+console.log(await client.contracts());
+// For an authorized operation, obtain its schema and provide its exact input:
+// await client.query({ name: 'conversation.list', payload: { ... } });
+```
+
+The service validates identity, tenant membership, account permissions and current grants. Installing this package grants no business access. Supply a short-lived authorized access token through a protected environment or your token provider; never commit credentials. Writes require an idempotencyKey. Unknown external effects must be inspected using their original operation, rather than resubmitted.
+
+Exports: RemoteNativeEngagementSdk, RemoteNativeEngagementError and their TypeScript types. SDK responses preserve the service's structured result and error semantics.
+
+This beta is distributed with license `UNLICENSED`; publication does not grant an open-source license. Product documentation: https://engagement.shipkitx.com/downloads

package/THIRD_PARTY_LICENSES.txt

@@ -0,0 +1 @@
+No third-party runtime code is bundled. Node.js built-in modules are provided by the host.

package/dist/index.d.ts

@@ -0,0 +1,91 @@
+// Generated by dts-bundle-generator v9.5.1
+
+export interface AgentStackScope {
+	readonly authorityRef: string;
+	readonly sourcePrincipal: Readonly<{
+		issuer: string;
+		subject: string;
+	}>;
+	readonly tenantId: string;
+	readonly workspaceId: string;
+	readonly projectId: string;
+	readonly businessAgentId: string;
+	readonly businessAgentVersionId: string;
+	/** 经签名的上游服务凭据租约 ID；正式生产端配对要求此字段以隔离轮换后的旧断言。 */
+	readonly sourceCredentialId?: string;
+}
+export interface TenantContextInput {
+	readonly tenantId?: string | undefined;
+	readonly principalRef?: string | undefined;
+	readonly actorRef?: string | undefined;
+	readonly authorizationScopes?: readonly string[] | undefined;
+	readonly projectRef?: string | undefined;
+	readonly workspaceRef?: string | undefined;
+	/** Signature-verified JWT issuer, never a caller-supplied business payload. */
+	readonly identityIssuer?: string | undefined;
+	/** Signature-verified JWT subject, never a caller-supplied business payload. */
+	readonly identitySubject?: string | undefined;
+	/** 只由验证签名的 Agent Stack 适配器产生，HTTP 业务 payload 不得提供。 */
+	readonly agentStack?: AgentStackScope | undefined;
+}
+declare const EXECUTION_NODE_PROTOCOL = "ne-execution-node/1.0";
+export interface NodeProof {
+	protocol: typeof EXECUTION_NODE_PROTOCOL;
+	tenantId: string;
+	serviceOrigin: string;
+	installationRef: string;
+	keyFingerprint: string;
+	nodeRef: string | null;
+	nodeGeneration: number;
+	nodeSessionRef: string | null;
+	sessionGeneration: number;
+	requestNonce: string;
+	bodyDigest: string;
+	signature: string;
+}
+export interface ContractExecutionRequest {
+	/** Transport possession proof is separate from verified identity. */
+	readonly transportProof?: NodeProof | undefined;
+	readonly name: string;
+	readonly payload?: Readonly<Record<string, unknown>> | undefined;
+	readonly context?: TenantContextInput | undefined;
+}
+export type TokenProvider = () => string | Promise<string>;
+export interface RemoteSdkOptions {
+	readonly nodeProof?: (method: string, route: string, payload: Readonly<Record<string, unknown>>) => NodeProof;
+	readonly baseUrl: string;
+	readonly accessToken: TokenProvider;
+	readonly fetchImpl?: typeof fetch;
+	/** Bound JSON response memory; 16 MiB by default, at most 64 MiB. */
+	readonly maximumResponseBytes?: number;
+	/** Only an optional tenant selector, never a source of authorization. */
+	readonly tenantId?: string;
+}
+export declare class RemoteNativeEngagementError extends Error {
+	readonly code: string;
+	readonly status: number;
+	readonly details: Readonly<Record<string, unknown>>;
+	readonly retryable: boolean;
+	readonly hint: string;
+	readonly retryAfterSeconds: number | undefined;
+	readonly reasonCode: string | undefined;
+	constructor(code: string, message: string, status: number, details?: Readonly<Record<string, unknown>>);
+}
+/**
+ * Public Agent SDK. For each operation, present a bearer credential to the
+ * service, which verifies identity and tenant. This client accepts no
+ * caller-provided principalRef or authorizationScopes.
+ */
+export declare class RemoteNativeEngagementSdk {
+	#private;
+	constructor(options: RemoteSdkOptions);
+	contracts(): Promise<unknown>;
+	schema(name: string): Promise<unknown>;
+	query(request: Pick<ContractExecutionRequest, "name" | "payload">, signal?: AbortSignal): Promise<unknown>;
+	command(request: Pick<ContractExecutionRequest, "name" | "payload">, signal?: AbortSignal): Promise<unknown>;
+	search(payload: Readonly<Record<string, unknown>>): Promise<unknown>;
+	enquiry(payload: Readonly<Record<string, unknown>>): Promise<unknown>;
+	agentStackPreflight(payload: Readonly<Record<string, unknown>>): Promise<unknown>;
+}
+
+export {};

package/dist/index.js

@@ -0,0 +1 @@
+function l(t){return t==="SEND_BUDGET_EXHAUSTED"?{retryable:!0,hint:"WAIT_FOR_ACCOUNT_BUDGET_AND_RETRY_SAME_KEY"}:t==="SEND_GATE_DISABLED"?{retryable:!1,hint:"REQUIRE_ACCOUNT_OWNER_TO_ENABLE_SENDING"}:t==="SEND_RESERVATION_REQUIRED"?{retryable:!1,hint:"CANCEL_AND_REVIEW_A_NEW_RESERVED_INTENT"}:["AUTH_VERIFICATION_UNAVAILABLE","AGENT_STACK_AUTHORITY_UNAVAILABLE","REDIS_RATE_LIMIT_UNAVAILABLE","SERVICE_NOT_CONFIGURED","RATE_LIMIT_EXCEEDED"].includes(t)?{retryable:!0,hint:"WAIT_AND_RETRY_SAME_IDEMPOTENCY_KEY"}:["AUTH_TOKEN_EXPIRED","AUTHENTICATION_REQUIRED","AUTH_TOKEN_REVOKED"].includes(t)?{retryable:!1,hint:"REAUTHENTICATE_AND_RECHECK_CURRENT_AUTHORITY"}:["ENTITY_CONFLICT","SEARCH_CURSOR_STALE","HOST_INBOX_CURSOR_STALE"].includes(t)?{retryable:!1,hint:"READ_CURRENT_STATE_AND_REPLAN"}:t==="IDEMPOTENCY_CONFLICT"?{retryable:!1,hint:"RESTORE_ORIGINAL_INPUT_FOR_KEY"}:["HOST_EXECUTION_FAILED","HOST_BRIDGE_UNAVAILABLE"].includes(t)?{retryable:!1,hint:"VERIFY_KNOWN_OPERATION_BEFORE_ANY_SEND"}:t==="SUPPRESSED"?{retryable:!1,hint:"STOP_CONTACT_AND_REQUIRE_HUMAN_REVIEW"}:t.startsWith("AUTH")||t==="TENANT_NOT_PROVISIONED"?{retryable:!1,hint:"REQUIRE_OPERATOR_AUTHORITY_REVIEW"}:{retryable:!1,hint:"FIX_INPUT_OR_INSPECT_STATE_BEFORE_RETRY"}}var f=class extends Error{code;statusCode;details;constructor(e,r,o,s={}){super(r),this.code=e,this.statusCode=o,this.details=s,this.name="NativeEngagementError"}};function p(t,e){if(!t||typeof t!="object"||Array.isArray(t))throw new f("VALIDATION_FAILED",`${e} must be an object.`,400,{field:e});return t}function I(t){let e=p(t??{},"payload"),r=e.idempotencyKey;if(typeof r!="string"||!r.trim()||r.length>1024*1024)throw new f("VALIDATION_FAILED","Every command requires a bounded idempotencyKey.",400,{field:"idempotencyKey"});return e}async function h(t,e=2*1024*1024){if(Number(t.headers.get("content-length"))>e||!t.body)throw Error("NODE_REMOTE_RESPONSE_TOO_LARGE");let r=t.body.getReader(),o=[],s=0;try{for(;;){let n=await r.read();if(n.done)break;if(s+=n.value.byteLength,s>e)throw Error("NODE_REMOTE_RESPONSE_TOO_LARGE");o.push(n.value)}let a=new Uint8Array(s),c=0;for(let n of o)a.set(n,c),c+=n.byteLength;return JSON.parse(new TextDecoder("utf-8",{fatal:!0}).decode(a))}finally{await r.cancel().catch(()=>{}),r.releaseLock()}}var E=class extends Error{constructor(r,o,s,a={}){super(o);this.code=r;this.status=s;this.details=a;this.name="RemoteNativeEngagementError";let c=l(r);this.retryable=c.retryable,this.hint=c.hint;let n=a.retryAfterSeconds,d=a.reasonCode;this.retryAfterSeconds=Number.isInteger(n)&&Number(n)>=0&&Number(n)<=3600?Number(n):void 0,this.reasonCode=typeof d=="string"&&/^[A-Z][A-Z_]{1,120}$/.test(d)?d:void 0}code;status;details;retryable;hint;retryAfterSeconds;reasonCode};function R(t){let e;try{e=new URL(t)}catch{throw new Error("Invalid native-engagement service URL.")}let r=e.hostname==="127.0.0.1"||e.hostname==="localhost"||e.hostname==="[::1]";if(!(e.protocol==="https:"||e.protocol==="http:"&&r)||e.username||e.password||e.search||e.hash||e.pathname!=="/")throw new Error("native-engagement requires HTTPS or HTTP loopback without URL credentials.");return e.origin}var A=class{#o;#i;#s;#r;#t;#n;constructor(e){if(this.#o=R(e.baseUrl),this.#i=e.accessToken,this.#s=e.fetchImpl??fetch,this.#n=e.tenantId,this.#r=e.nodeProof,this.#t=e.maximumResponseBytes??16*1024*1024,!Number.isSafeInteger(this.#t)||this.#t<1024||this.#t>64*1024*1024)throw Error("Invalid maximum JSON response size.")}async#e(e,r,o,s=!0,a=3e4,c){let n={accept:"application/json","content-type":"application/json"};if(s){let i=await this.#i();if(!/^[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+$/.test(i))throw new E("AUTHENTICATION_REQUIRED","An access token is required for the remote operation.",401);n.authorization=`Bearer ${i}`,this.#n&&(n["x-tenant-id"]=this.#n)}this.#r&&/^\/v1\/(query|command)\/execution\.node\./.test(r)&&(n["x-execution-node-proof"]=Buffer.from(JSON.stringify(this.#r(e,r,o??{}))).toString("base64url"));let d=await this.#s(`${this.#o}${r}`,{method:e,headers:n,...e==="POST"?{body:JSON.stringify(o??{})}:{},redirect:"error",signal:c?AbortSignal.any([c,AbortSignal.timeout(a)]):AbortSignal.timeout(a)}),u;try{u=await h(d,this.#r&&r.includes("/execution.node.")?2*1024*1024:this.#t)}catch{throw new E("REMOTE_RESPONSE_INVALID","The service did not return valid JSON.",d.status)}if(!d.ok){let i=u&&typeof u=="object"&&"error"in u?u.error:void 0;throw new E(i?.code??"REMOTE_REQUEST_FAILED",i?.message??"The native-engagement service rejected the request.",d.status,i?.details&&typeof i.details=="object"&&!Array.isArray(i.details)?i.details:{})}return u}contracts(){return this.#e("GET","/v1/contracts",void 0,!1)}schema(e){return this.#e("GET",`/v1/contracts/${encodeURIComponent(e)}`,void 0,!1)}query(e,r){let o=["channel.status.inspect","profile.host.inspect","wechat.session.inspect","wechat.thread.observe","browser.session.inspect","browser.thread.observe"].includes(e.name)?12e4:3e4;return this.#e("POST",`/v1/query/${encodeURIComponent(e.name)}`,e.payload,!0,o,r)}command(e,r){try{I(e.payload)}catch{throw new E("VALIDATION_FAILED","Every command requires a bounded idempotencyKey.",400)}let o=["conversation.source.sync","conversation.source.rebase","wechat.conversation.sync","wechat.thread.link","wechat.watch.resume"].includes(e.name)||e.name==="asset.speech.synthesize"?12e4:["message.text.execute","message.text.verify","wechat.message.execute","wechat.message.verify"].includes(e.name)?18e4:["asset.parse","message.attachment.capture","work.content.prepare","work.mail.content.prepare","work.source.content.prepare"].includes(e.name)?2e5:3e4;return this.#e("POST",`/v1/command/${encodeURIComponent(e.name)}`,e.payload,!0,o,r)}search(e){return this.#e("POST","/v1/search",e)}enquiry(e){return this.#e("POST","/v1/enquiry",e)}agentStackPreflight(e){return this.#e("POST","/v1/integrations/agent-stack/preflight",e)}};export{E as RemoteNativeEngagementError,A as RemoteNativeEngagementSdk};

package/package.json

@@ -1,6 +1,32 @@
 {
   "name": "@native-engagement/sdk",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.8.0",
+  "type": "module",
+  "description": "Authenticated remote TypeScript client for Native Engagement",
+  "engines": {
+    "node": ">=24.22.1 <25"
+  },
+  "license": "UNLICENSED",
+  "files": [
+    "dist",
+    "README.md",
+    "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"
+  },
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  }
+}

package/release.json

@@ -0,0 +1,7 @@
+{
+  "schemaVersion": 1,
+  "sourceCommit": "5402e30207f693b0a0e28cb49e54720b402e1db9",
+  "channel": "beta",
+  "bundledComponents": [],
+  "lockSha256": "421cbab359e454443023383a61d63b1fc9f562e79c4e7c5174b09bdfb640d76c"
+}