@collective-intelligence/external-apps-server-sdk 0.1.4 → 0.1.5

package/README.md

@@ -427,6 +427,54 @@ succeeded before the new turn started count. A turn is
   subject, never with the application's scopes. Visitors are separate owners:
   one visitor never reads another visitor's conversation.
 
+## Messages
+
+`messages.send` sends one message through a messaging connection of the
+Organization, for example a Telegram bot or a WhatsApp Business Account. The
+application needs the `messaging:send` scope, and an administrator must grant
+the connection to the application on its administration page.
+
+```ts
+const sent = await ci.messages.send({
+  connectionId,
+  content: { kind: "text", text: "Your order is ready." },
+  idempotencyKey: `order-${orderId}-ready`,
+  organizationId,
+  target: { conversation, mode: "continue" }
+})
+// sent.value.result: { conversation, messageId }
+```
+
+- `target` continues a conversation with the Conversation Reference of an
+  earlier message (`{ mode: "continue", conversation }`), or starts one with
+  the recipient fields of the vendor (`{ mode: "start_new", recipient }`).
+- `content` is a text, or `{ kind: "voice", text, voice }` for a text that CI
+  speaks.
+- `sender` holds the sender fields of the vendor, for example
+  `{ phoneNumberId }`. It is required when the account has more than one
+  sender. `service` names the vendor service when the connection has more
+  than one.
+- The result is the Message Receipt: the message id of the vendor and the
+  Conversation Reference that continues the conversation. It means that the
+  vendor accepted the message, not that a person received it.
+- `idempotencyKey` (at most 256 characters; generated when omitted) makes a
+  repeat safe. A repeat with the same key and content returns the first
+  outcome and sends nothing. A repeat with the same key and other content
+  returns `conflict`. Use your own key when your server can repeat a send
+  after a crash.
+- CI sends once and never retries a failed send. A failed send returns
+  `message_send_failed` with a `sendErrorCode`, for example `window_closed`,
+  `recipient_unreachable`, `template_required` or `transport`. The same key
+  returns the same failure: use a new key to send again.
+- `send_outcome_unknown` means that the first send with the key has no
+  recorded outcome: it still runs, or CI stopped before it recorded the
+  outcome. CI does not send again for the key. Repeat the call later; if the
+  answer stays the same, check with the vendor before you send with a new key.
+- `not_found` means that the connection does not exist or is not granted to
+  the application. `rate_limited` (HTTP 429) means that the connection
+  reached its rate limit; it is retryable, and the client repeats it with the
+  same key.
+
 ## Member users
 
 A confidential application administers the `member` users of its own
@@ -503,11 +551,18 @@ const links = await ci.users.listCompanyLinks({ organizationId, userId })
 - A delegated user's `/application/v1/resources` and `knowledge_*` calls, and
   the Agents, Skills and workflows the user runs, carry the user's links to
   Knowledge policy as `subject.linkedCompanyIds`, and a policy reads the
-  entity id as `resource` path `["id"]`. To keep `member`-role users to their
-  own companies, declare a `deny` `filter` policy on the company schema: subject
-  match `user.role` equals `member`, rule "entity id not in
-  `linkedCompanyIds`". Gets and writes of any other company, creates included,
-  then fail with `forbidden` and lists omit it; other roles and service
+  entity id as `resource` path `["id"]`. CI also sets `subject.access`:
+  `"read"` for gets, lists, searches, facets, autocomplete, traversal and
+  retrieval, `"write"` for creates, updates, deletes and relation writes. The
+  operation sets it; a caller cannot. A policy that does not test `access`
+  applies to reads and writes alike.
+- To let `member`-role users write only their own companies but read every
+  company (for example through member-run Agents), declare a `deny` `filter`
+  policy on the company schema: subject match `user.role` equals `member` and
+  `access` equals `write`, rule "entity id not in `linkedCompanyIds`". Updates
+  and deletes of any other company, and creates, then fail with `forbidden`;
+  gets, lists and searches still return it. Without the `access` clause the
+  same policy also hides other companies from reads. Other roles and service
   credentials are unaffected.
 - The policy binds an execution only while it acts as the member. An Agent or
   Skill tool bound to a fixed user, or a workflow that runs as another user or
@@ -1159,6 +1214,9 @@ OAuth client may supply `clientSecret`; a public PKCE client omits it.
 `CI_CLIENT_SECRET`. `readApplicationEnrollment` reads those variables, so the
 application names none of them. It throws a `TypeError` that lists every
 missing variable. Pass the same prefix as `--prefix` when it is not `CI_`.
+`ci apps env <application>` prints the same variables for an application that
+already exists, for example to copy them into a deployment pipeline; it leaves
+out `CI_CLIENT_SECRET`, which CI shows only once.
 
 ```ts
 import {

package/dist/admin.d.ts

@@ -4965,6 +4965,7 @@ declare const createAdministrationApi: (client: Client$1) => {
 			description: string | null;
 			directChildCount: number;
 			directMemberCount: number;
+			fqn: string | null;
 			id: string;
 			inheritedMembershipImpact: {
 				descendantGroupCount: number;
@@ -4973,6 +4974,11 @@ declare const createAdministrationApi: (client: Client$1) => {
 			};
 			name: string;
 			organizationId: string;
+			package: {
+				fqn: string;
+				managed: boolean;
+				readonly: boolean;
+			} | null;
 			parentGroupId: string | null;
 			parentPath: Array<{
 				id: string;
@@ -5001,6 +5007,7 @@ declare const createAdministrationApi: (client: Client$1) => {
 				description: string | null;
 				directChildCount: number;
 				directMemberCount: number;
+				fqn: string | null;
 				id: string;
 				inheritedMembershipImpact: {
 					descendantGroupCount: number;
@@ -5009,6 +5016,11 @@ declare const createAdministrationApi: (client: Client$1) => {
 				};
 				name: string;
 				organizationId: string;
+				package: {
+					fqn: string;
+					managed: boolean;
+					readonly: boolean;
+				} | null;
 				parentGroupId: string | null;
 				parentPath: Array<{
 					id: string;