@native-marketing/sdk 0.1.1 → 0.3.0

package/README.md

@@ -14,12 +14,21 @@ 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);
+  const page = await native.discoverCapabilities({ query: '检查连接状态和当前项目' });
+  const item = page.items[0];
+  if (!item) return; // NO_MATCH applies to the currently authorized catalogue.
+  const exact = await native.describeCapability(item.name, item.schemaSha256);
+  const context = await native.readCapability({
+    name: item.name,
+    expectedSchemaSha256: exact.schemaSha256,
+    arguments: {},
+    delivery: 'ORIGINAL',
+  });
+  console.log(context);
 });
 ```
 
-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.
+The server filters discovery using current object, OAuth scopes and business permissions. `discoverCapabilities` uses AGENT_V3 bilingual action/object matching and explicit scoped NO_MATCH. Small results include the exact schema and fingerprint; `describeCapability(name, observedHash)` reuses a verified, bounded connection-local cache or loads the definition on demand. Every execution still checks current authorization and the fingerprint. The existing `findCapabilities` retains its v2 response contract. Search saved business content with `searchBusiness`; use `getBusinessSummary` for a bounded summary and nextActions. 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.
 
@@ -37,4 +46,22 @@ const native = createContentFactoryClient({ baseUrl: 'https://ip.shipkitx.com/ap
 
 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.
 
+## Tenant application connections and event permissions
+
+Use the exact authorized `/mcp/tenants/TEN-*` resource with `cf.context.read`, `cf.knowledge.manage` and the current Tenant's `permissions.manage` permission. Project resources cannot administer Tenant event connections.
+
+```ts
+await withNativeAgentClient({ resource, accessToken }, async (native) => {
+  const connections = await native.callTool('cf_list_event_exchanges', { limit: 20 });
+  const schema = await native.describeCapability('cf_configure_event_exchange');
+  console.log(connections.result, schema.definition);
+});
+```
+
+`cf_configure_event_exchange` registers or revokes one exact EventSDK event-type Grant with the original `requestId` and current Connection `expectedRevision`. Inspect the current schema and confirm the precise source/target Tenant refs, consumer, event type and grant version before writing; events are never selected or authorized automatically. Other event types remain unchanged. Local ACTIVE does not grant peer consent, Broker access or resource readability.
+
+Recover an unknown configure result using `cf_get_event_exchange_receipt` with the original requestId. `cf_list_event_outbox` reads one bounded page and backlog/Worker observation. An explicitly authorized `cf_recover_event_outbox` command preserves the original delivery identity and expectedGeneration; UNKNOWN uses `cf_get_event_outbox_recovery_receipt`, without replaying the command. Read each receipt under the same authorized resource/client. Receipt absence does not permit another write. Authorization management does not emit a new authorization-change CloudEvent.
+
+The HTTP subpath includes typed GET/POST `/tenants/{tenantCode}/event-exchanges`, receipt and Outbox endpoints. HTTP uses the existing authorized Session; MCP uses resource-bound OAuth. Tenant and authorization facts remain in Native Marketing's database.
+
 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).