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

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
@@ -1149,7 +1204,100 @@ The store persists only hashed opaque-cookie state, token grants and revisions;
 the browser receives a `Secure`, `HttpOnly`, `SameSite=Lax` host cookie. Every
 session lookup revalidates the short-lived CI identity. Revoked or expired CI
 access ends application authorization on the next validation. A confidential
-OAuth client may supply `clientSecret`; a public PKCE client omits it.
+OAuth client may supply `clientSecret`; a public PKCE client omits it. The
+client type decides how long the User session lasts; see
+[Session lifetime and renewal](#session-lifetime-and-renewal).
+
+### Session lifetime and renewal
+
+`sessionTtlSeconds` sets the Session lifetime: the time from sign-in to the
+end of the User session. The default is `86400` (one day). The SDK accepts an
+integer from `300` to `604800` (seven days).
+
+A User session lasts its Session lifetime only with renewal. Without renewal,
+the User session ends when its Access token expires, 300 seconds after
+sign-in, whatever the value of `sessionTtlSeconds`. The Access token lifetime
+is always 300 seconds. There is no setting for it.
+
+Renewal needs these three conditions:
+
+- The external Application is confidential at CI.
+- `createFederatedAuth` gets the `clientSecret` of that Application.
+- The user signed in after the upgrade to an SDK version that renews. An
+  earlier cookie or store record holds no Renewal credential. That User
+  session ends at its Access token expiry.
+
+When the three conditions are true, CI returns a Renewal credential at
+sign-in. On the wire it is the OAuth `refresh_token`. The SDK keeps it in the
+session record and uses it to get a new Access token with no browser redirect.
+The application code does not change.
+
+A public client has no client secret, so it gets no Renewal credential. Its
+User session lasts 300 seconds. To continue, the application sends the browser
+to `<basePath>/login` again, as before. A `fetch` call or a form post cannot
+follow that redirect. For a public client, `createFederatedAuth` still accepts
+each `sessionTtlSeconds` value in the range and gives no warning.
+
+`getSession`, `getAccessToken`, `getEntityContext` and
+`GET <basePath>/session` are the session lookups. With renewal, each lookup
+first gets a new Access token when the current one is expired or expires in 30
+seconds or less. Then it checks the current identity at `/oauth/identity`. A
+lookup never returns an expired Access token. Lookups at the same time share
+one renewal request.
+
+The SDK writes the cookie or the store record one time, at sign-in. A renewal
+writes no cookie and no store record. A renewed Access token stays only in
+process memory. Each `createFederatedAuth` instance keeps at most 5000 of
+them, separate from each other instance. A restart loses them, and the next
+lookup renews again.
+
+A Federated authorization is the record that CI keeps of one sign-in to one
+external Application. It lasts at most 604800 seconds from sign-in, and never
+longer than the CI session of the user. The User session ends at the earlier
+of these two times:
+
+- sign-in plus `sessionTtlSeconds`;
+- the end of the Federated authorization.
+
+`expiresAt` of the session reports that end. It is the same at each lookup,
+because a lookup does not extend the User session. Without a Renewal
+credential, `expiresAt` stays the Access token expiry.
+
+A lookup has one of three results:
+
+- **A session.** CI accepts the identity, after a renewal when one is
+  necessary.
+- **`null`**, and `401` on `GET <basePath>/session`. CI refuses the user or
+  the Federated authorization: it answers `invalid_grant` to the renewal, or
+  it refuses the identity. The result is also `null` after the end of the User
+  session. Send the user to the login route.
+- **`ApplicationUserAuthUnavailableError`**, and `503` on
+  `GET <basePath>/session`. The client secret is wrong or rotated
+  (`invalid_client`), CI gives another OAuth error, or CI does not answer. The
+  User session stays. It returns when the fault is corrected, with no
+  sign-in.
+
+A renewal applies the same admission rule as `/oauth/identity`:
+
+- the external Application is enabled;
+- the CI session is live;
+- the user is not banned and is still admitted to the Organization, which
+  today means the Organization membership of the user and its role;
+- the scopes of the sign-in are still allowed.
+
+A refusal ends nothing. When the condition is corrected, the same Renewal
+credential renews again. A Federated authorization ends for good only by one
+of these events: logout, a new sign-in in the same User session, its limit of
+604800 seconds, or the end of the CI session.
+
+`POST <basePath>/logout` presents the Renewal credential to CI, and CI ends
+the Federated authorization. If CI does not answer, the route answers `503`
+and still clears the User session. That Federated authorization then ends at
+its limit or with its CI session.
+
+An application that does not use this SDK finds the CI token and logout
+contract in
+[Access token renewal](../../../docs/architecture/external-app-gateway.md#access-token-renewal).
 
 ### Configure from the CLI enrollment
 
@@ -1159,6 +1307,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;

package/dist/auth/federated.d.ts

@@ -125,6 +125,10 @@ declare class FederatedAuthRejectedError extends Error {
 export type FederatedGrant = Readonly<{
 	accessToken: string;
 	expiresAt: number;
+	/** Renewal credential of the Federated authorization; set together with `refreshExpiresAt`. */
+	refreshToken?: string;
+	/** Epoch milliseconds at which the Renewal credential stops; set together with `refreshToken`. */
+	refreshExpiresAt?: number;
 }>;
 export type FederatedLogin = Readonly<{
 	status: "idle";