Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
37 commits
Select commit Hold shift + click to select a range
96f1383
fix(ui): Inbox shows its list beside the thread from 560px; Back only…
purpshell Oct 25, 2026
3e2d4e0
feat!: consolidate the browser UI packages into @polymorfa/ui-kit
purpshell Oct 26, 2026
9e893a2
chore: bind documentation snippets to the UI Kit consolidation
purpshell Oct 26, 2026
9d5d18c
feat: client tokens can carry groups_read and groups_manage; fix call…
purpshell Oct 27, 2026
3a0a642
feat(ui-kit): new chat, contacts directory and group support
purpshell Oct 27, 2026
1e33869
test(ui-kit): cover new chat, contacts and groups across controllers,…
purpshell Oct 27, 2026
fc3bb8f
feat(ui-kit): name group members from contacts; no Saved for reading …
purpshell Oct 27, 2026
550c0ca
docs(ui-kit): new chat, contacts and groups
purpshell Oct 27, 2026
a920f1d
feat(ui-kit): call log controller and views; handler call history
purpshell Oct 27, 2026
2fafcee
fix(ui-kit): public contact lists use the shared shell
purpshell Oct 27, 2026
b4ea1f2
feat: call log from the API with caller identity
purpshell Oct 27, 2026
3b16c61
feat: client tokens cover a messaging frontend in all SDKs and the UI…
purpshell Oct 27, 2026
efca357
fix(ui-kit): composer field and buttons share one control size
purpshell Oct 27, 2026
a3f6b51
feat: list a number's calls from its data region in all six SDKs
purpshell Oct 28, 2026
85eb685
chore: bind documentation snippets to the session calls SDK change
purpshell Oct 28, 2026
0196b5f
Merge accepted SDK main into the UI Kit feature candidate
purpshell Oct 30, 2026
350df5c
docs: align group authority and native call history examples
purpshell Oct 30, 2026
5c18165
docs: distinguish UI Kit and call history source from published packages
purpshell Oct 30, 2026
8b658df
test(dotnet): isolate Number call history wire qualification
purpshell Oct 30, 2026
94d28a4
Merge current main and repair UI Kit grant, call and group flows
purpshell Nov 5, 2026
43d9f2e
Bind verified documentation snippets to reconciled SDK source
purpshell Nov 5, 2026
08f4e1a
Merge origin/main into feat/ui-kit-new-chat-contacts-groups-20261027
purpshell Nov 12, 2026
ec8ccbb
Merge origin/main into feat/ui-kit-new-chat-contacts-groups-20261027
purpshell Nov 12, 2026
0b58817
docs: rebind doc snippets to merge commit
purpshell Nov 12, 2026
1e04d79
Merge polymorfa/sdks main into UI Kit new chat, contacts, groups and …
purpshell Nov 12, 2026
b18e818
docs: rebind doc snippets to the main merge source
purpshell Nov 12, 2026
a15444a
Merge polymorfa/sdks main into UI Kit new chat, contacts, groups and …
purpshell Nov 16, 2026
31c8529
docs: rebind doc snippets to the main merge source
purpshell Nov 16, 2026
29390ff
fix(ui-kit): ContactList waits for the first grant; cached group hist…
purpshell Nov 16, 2026
c0f5dbf
docs: rebind doc snippets to the review fixes
purpshell Nov 16, 2026
f1890e7
fix(ui-kit): cached group authors never rename the group
purpshell Nov 16, 2026
fc8b644
Merge polymorfa/sdks main into UI Kit new chat, contacts, groups and …
purpshell Nov 16, 2026
3e99520
docs: rebind doc snippets to the main merge source
purpshell Nov 16, 2026
e346866
fix(ui-kit): only a fresh display name can name a conversation
purpshell Nov 16, 2026
db8f566
fix(ui-kit): address CodeRabbit and Codex review of 3e99520b
purpshell Nov 16, 2026
641230d
Merge polymorfa/sdks main into UI Kit new chat, contacts, groups and …
purpshell Nov 16, 2026
9fab0e8
docs: rebind doc snippets to the main merge source
purpshell Nov 16, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
68 changes: 68 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,74 @@

## Unreleased

- Client tokens cover a messaging frontend. All six SDKs, the drop-in handler
and the UI Kit accept the new session actions `conversations_read`,
`conversations_manage`, `labels_read`, `labels_manage`, `contacts_manage`,
`profile_read`, `profile_manage`, `channels_read`, `channels_manage`,
`business_read` and `presence_write`. Customer-scoped tokens accept every
action except `mcp`, including Calls, groups and call records. Requires the
matching API change.
- UI Kit: `client.messaging()` gains `chats` (history, archive, disappearing
messages, edit and delete), `labels`, `profile` (profile and privacy),
`channels`, `catalog`, `presence.set`, contact block, unblock and info, and
`groups.setPicture` (base64). Browser Calls take `clientTokenSession` so a
Customer token names the number it calls from.

- A number's call history with the other party's identity: `GET
/messaging/{session}/calls` in all six SDKs (`calls.list`,
`SessionCalls().List` in Go, `Calls.ListAsync` in .NET). `peer` carries the
user ID, phone number and username. Records are served from the number's
data region; client tokens need the new `read_calls` action. Platform call
records are unchanged and keep `peerRef`. Requires the matching API change.
- UI Kit call log: `<CallLog/>`, `<pmfa-call-log>` and an Inbox Chats/Calls
switch read the number's calls from the API, merge repeat calls as WhatsApp
does and offer call back. `ContactListView` now takes `className` and
`classNames`; `ContactList` and `<pmfa-contact-list>` show the Contacts list
on their own.
- Drop-in handler: call events without a known peer are no longer relayed to
grants limited to conversations.

- UI Kit: New chat and a contacts directory. `<NewChat/>` and
`<pmfa-new-chat>` list the WhatsApp account's contacts (`read_contact`),
search names without regard to case or accents, check unsaved numbers and
open the chosen chat as a draft until its first message. The Inbox shows
them from its New chat button.
- UI Kit: groups. `<GroupDetails/>` and `<pmfa-group-details>` show a group's
info and members and make the changes client tokens allow: create, rename,
describe, add and remove members, promote and demote admins, read and reset
the invite link, the four settings and exit. Group threads name each
message's author. Framework-neutral `ContactDirectoryController`,
`NewChatController`, `GroupController` and `client.messaging().groups`
back both. Relayed group messages no longer rename the chat after their
sender.
- Client tokens: `groups_read` and `groups_manage` in all six server SDKs,
the drop-in handler and the UI Kit, for session and Customer tokens. Requires the
matching API change; until it is accepted the API refuses these actions.
- UI Kit calls: toggle buttons no longer report `aria-pressed` alongside an
action label ("Turn camera on", pressed).
- UI Kit Inbox: with a custom `source` and no provider client, opening a
conversation with a phone number no longer throws from the call button.
- UI Kit: `<ContactList/>` without a custom source waits for the token's
first grant before loading, as `<NewChat/>` does, instead of failing with a
permission error. The browser store keeps a group message's author when it
caches backend history, so later local reads still name each sender, without
ever using an author's name as the group's name.
`MessageInput` gains optional `senderId` and `pushName`.
- UI Kit: `<CallLog/>` and `<GroupDetails/>` also wait for the first grant
before loading, so manage controls appear once `groups_manage` arrives.
`<GroupDetails/>` follows a new `groupId` instead of changing the first
group. The call log keeps calls with different outcomes on separate rows,
keeps live updates that arrive during a reload, shows a failed page beside
the loaded calls, and `<pmfa-call-log>` reads with a replacement client.
The Inbox keeps a chat opened while its list loads, keeps a direct message
with `isGroup: false` direct, opens chats from cached panels in the current
controller, gives open panels a new configuration and resets the group-info
toggle when the panel closes. `<pmfa-new-chat>` offers New group once a
later grant allows it and honours `no-groups` for host controllers.
`<pmfa-group-details>` keeps an unsaved edit across renders, loads
replacement contacts at once and can be moved in the document. A group read
that finishes after leaving no longer marks the group ready again.

- Breaking: Test number phone and event methods use the Number-scoped routes
in API contract revision `f180dc1ee2`. `testing.getPhone`, `sendPhoneMessage`
and `unlinkPhoneDevice` take a Number ID and no project argument, and
Expand Down
4 changes: 2 additions & 2 deletions contracts/doc-snippets.json
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
{
"schemaVersion": 1,
"sourceCommit": "f8a64f81955e87f7a3ff64c3f15061a1e967bd0c",
"sourceFilesSha256": "a470c775eb94e39111bd251c255076caad4236ed1b5ecb4284d7b620aa2e54fa",
"sourceCommit": "641230d38744d862cbf66ae3af56fbfb203e1e73",
"sourceFilesSha256": "2c9b8c527fdebf3ca68ffb320c2ac118778502c74571365cd116c53427b475f8",
"apiVersion": "2026-09-22",
"apiSourceCommit": "f180dc1ee2bd45dbecf01702f73bdd75c664634b",
"specs": {
Expand Down
14 changes: 13 additions & 1 deletion packages/calls/src/api.ts
Original file line number Diff line number Diff line change
Expand Up @@ -146,6 +146,12 @@ export interface HttpCallsApiOptions {
readonly fetch?: FetchLike;
/** Socket host; defaults to `ws(s)://` on the API host. */
readonly socketBaseUrl?: string;
/**
* The number a Customer-scoped client token acts for, sent as `?session=`
* on every Calls request. Session tokens are bound to one number and need
* no value.
*/
readonly clientTokenSession?: string;
readonly now?: () => number;
}

Expand Down Expand Up @@ -201,8 +207,10 @@ export class HttpCallsApi implements CallsApi {
readonly #baseUrl: string;
readonly #fetch: FetchLike;
readonly #socketBaseUrl: string;
readonly #clientTokenSession: string | undefined;

constructor(options: HttpCallsApiOptions) {
this.#clientTokenSession = options.clientTokenSession;
const credential = options.token ?? options.apiKey;
if (credential === undefined)
throw new CallsApiError(
Expand Down Expand Up @@ -445,7 +453,11 @@ export class HttpCallsApi implements CallsApi {
...(payload === undefined ? {} : { body: JSON.stringify(payload) }),
...(signal === undefined ? {} : { signal }),
};
const response = await this.#fetch(`${this.#baseUrl}${path}`, init);
const target =
this.#clientTokenSession !== undefined && isClientToken(token.value)
? `${path}${path.includes("?") ? "&" : "?"}session=${encodeURIComponent(this.#clientTokenSession)}`
: path;
const response = await this.#fetch(`${this.#baseUrl}${target}`, init);
const text = await response.text();
let parsed: unknown = undefined;
if (text.length > 0) {
Expand Down
12 changes: 12 additions & 0 deletions packages/calls/src/client.ts
Original file line number Diff line number Diff line change
Expand Up @@ -36,6 +36,12 @@ export interface CallsClientOptions {
* default `default`). Client tokens always act as their own participant.
*/
readonly participant?: string;
/**
* The number a Customer-scoped client token acts for, sent as `?session=`
* on Calls requests and the lifecycle socket. Leave unset for session
* tokens and server credentials.
*/
readonly clientTokenSession?: string;
/** Defaults to `https://api.polymorfa.com`. */
readonly baseUrl?: string;
/** Media reattach attempts after an unexpected drop. Default 3. */
Expand Down Expand Up @@ -152,6 +158,9 @@ export class CallsClient extends Emitter<ClientEvents> {
this.#api =
options.api ??
new HttpCallsApi({
...(options.clientTokenSession === undefined
? {}
: { clientTokenSession: options.clientTokenSession }),
token: credential!,
...(options.baseUrl === undefined ? {} : { baseUrl: options.baseUrl }),
...(options.fetch === undefined ? {} : { fetch: options.fetch }),
Expand All @@ -165,6 +174,9 @@ export class CallsClient extends Emitter<ClientEvents> {
...(options.participant === undefined
? {}
: { participant: options.participant }),
...(options.clientTokenSession === undefined
? {}
: { clientTokenSession: options.clientTokenSession }),
...timerOptions(options),
...(options.now === undefined ? {} : { now: options.now }),
});
Expand Down
12 changes: 10 additions & 2 deletions packages/calls/src/lifecycle.ts
Original file line number Diff line number Diff line change
Expand Up @@ -43,6 +43,8 @@ export interface LifecycleSocketOptions {
* Ignored for client tokens.
*/
readonly participant?: string;
/** The number a Customer-scoped client token acts for, sent as `?session=`. */
readonly clientTokenSession?: string;
readonly WebSocket?: typeof globalThis.WebSocket;
readonly setTimeout?: typeof globalThis.setTimeout;
readonly clearTimeout?: typeof globalThis.clearTimeout;
Expand Down Expand Up @@ -499,9 +501,15 @@ export class LifecycleSocket extends Emitter<Events> {
}
}

/** `/voip/ws`, naming the session only for server credentials. */
/**
* `/voip/ws`. Server credentials name the session and participant; a
* Customer-scoped client token names only the number it acts for.
*/
#path(token: CallsToken): string {
if (isClientToken(token.value)) return LIFECYCLE_SOCKET_PATH;
if (isClientToken(token.value))
return this.#o.clientTokenSession === undefined
? LIFECYCLE_SOCKET_PATH
: `${LIFECYCLE_SOCKET_PATH}?session=${encodeURIComponent(this.#o.clientTokenSession)}`;
const query = new URLSearchParams();
if (this.#o.session !== undefined) query.set("session", this.#o.session);
if (this.#o.participant !== undefined)
Expand Down
23 changes: 23 additions & 0 deletions packages/calls/test/lifecycle.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -336,3 +336,26 @@ describe("LifecycleSocket listener failures", () => {
h.socket.close();
});
});

describe("Customer-scoped client tokens", () => {
it("names the number on the lifecycle socket", async () => {
FakeWebSocket.instances = [];
const t = timers();
const socket = new LifecycleSocket({
api: fakeApi(),
session: "support",
clientTokenSession: "sales",
WebSocket: FakeWebSocket as unknown as typeof globalThis.WebSocket,
setTimeout: t.setTimeout,
clearTimeout: t.clearTimeout,
setInterval: t.setInterval,
clearInterval: t.clearInterval,
});
void socket.connect().catch(() => undefined);
await flush();
expect(FakeWebSocket.instances[0]!.url).toBe(
"wss://api.example/voip/ws?session=sales",
);
socket.close();
});
});
27 changes: 27 additions & 0 deletions packages/calls/test/social.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -81,3 +81,30 @@ describe("call interactions", () => {
expect(fetch).toHaveBeenCalledTimes(2);
});
});

describe("Customer-scoped client tokens", () => {
it("send ?session= on Calls requests only when a number is named", async () => {
const fetch = vi.fn<(url: string, init: RequestInit) => Promise<Response>>(
async () =>
new Response(JSON.stringify({ success: true }), {
status: 202,
headers: { "content-type": "application/json" },
}),
);
await new HttpCallsApi({
token: "pmfa_ct_dG9rZW4",
fetch,
baseUrl: "https://api.x",
clientTokenSession: "sales",
}).sendReaction("call", "connection-1", "👍");
await new HttpCallsApi({
token: "pmfa_ct_dG9rZW4",
fetch,
baseUrl: "https://api.x",
}).sendReaction("call", "connection-1", "👍");
expect(fetch.mock.calls.map(([url]) => url)).toEqual([
"https://api.x/messaging/voip/calls/call/reaction?session=sales",
"https://api.x/messaging/voip/calls/call/reaction",
]);
});
});
18 changes: 18 additions & 0 deletions packages/dotnet/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -1120,6 +1120,24 @@ Task<ApiResponse<SuccessEnvelope<PasskeyConfirmation>>> ConfirmExplicitly() =>
client.Passkeys.ConfirmAsync(session, suppliedConfirmation);
```

## Number call history (unreleased source)

Read one number's calls with the other party's identity through
`GET /messaging/{session}/calls`. Client tokens need `read_calls`.
The route requires the regional call-history API deployment; this source
change does not make it available on a deployed API or package registry.

```csharp
var page = await messaging.Calls.ListAsync("support",
new ListSessionCallsParameters(Limit: 25, Outcome: "missed"));
```

The response contains `data` and a nullable `nextCursor` (`Data` and
`NextCursor` in .NET; `next_cursor` in Rust). Pass a returned cursor in the
next request. Filters include direction, outcome and ISO 8601 start-time
bounds `since`/`until`. `peer` may be null; its user ID, phone number and
username may each be absent. Platform call records keep `peerRef`.

## Number-scoped Test operations

The Test phone methods take a Number ID, without a project argument:
Expand Down
2 changes: 2 additions & 0 deletions packages/dotnet/src/Polymorfa.Sdk/Calls.cs
Original file line number Diff line number Diff line change
Expand Up @@ -76,6 +76,8 @@ public Task<ApiResponse<SuccessEnvelope<PlacedCall>>> PlaceAsync(PlaceCallReques
Participant(body.Participant); return http.RequestAsync<SuccessEnvelope<PlacedCall>>(HttpMethod.Post, "/messaging/voip/calls", body, options);
}
public Task<ApiResponse<SuccessEnvelope<AcceptedCall>>> AcceptAsync(string callId, AcceptCallRequest? body = null, RequestOptions? options = null) { body ??= new(); Participant(body.Participant); return http.RequestAsync<SuccessEnvelope<AcceptedCall>>(HttpMethod.Post, Path(callId) + "/accept", body, options); }
/// <summary>One page of the number's calls, newest first, with the other party's identity. Records are served from the number's data region; client tokens need the read_calls action.</summary>
public Task<ApiResponse<SessionCallsPage>> ListAsync(string session, ListSessionCallsParameters? parameters = null, RequestOptions? options = null) => http.RequestAsync<SessionCallsPage>(HttpMethod.Get, $"/messaging/{Uri.EscapeDataString(session)}/calls", null, options, Resource.Query(parameters ?? new()));
public Task<ApiResponse<RejectIncomingCallResponse>> RejectIncomingAsync(string session, string callId, RejectIncomingCallRequest body, RequestOptions? options = null) => http.RequestAsync<RejectIncomingCallResponse>(HttpMethod.Post, $"/messaging/{Uri.EscapeDataString(session)}/calls/{Uri.EscapeDataString(callId)}/reject", body, options);
public Task<ApiResponse<SuccessResponse>> RejectAsync(string callId, RejectCallRequest? body = null, RequestOptions? options = null) { Participant(body?.Participant); return http.RequestAsync<SuccessResponse>(HttpMethod.Post, Path(callId) + "/reject", body?.Participant is null ? null : body, options); }
public Task<ApiResponse<SuccessResponse>> LeaveAsync(string callId, LeaveCallRequest body, RequestOptions? options = null) { Connection(body.ConnectionId); Participant(body.Participant); return http.RequestAsync<SuccessResponse>(HttpMethod.Post, Path(callId) + "/leave", body, options); }
Expand Down
7 changes: 7 additions & 0 deletions packages/dotnet/src/Polymorfa.Sdk/MessagingModels.cs
Original file line number Diff line number Diff line change
Expand Up @@ -67,5 +67,12 @@ public sealed record HistoryMediaRetrieval(string State, string? Reason = null);
public sealed record HistoryPollOption(string Name, string Hash);
public sealed record HistoryMessage(string Id, [property: JsonPropertyName("whatsapp_ids")] WhatsAppMessageIds WhatsAppIds, string Direction, string Type, string Timestamp, HistoryConversation Conversation, bool FromMe, string? PushName = null, string? Text = null, string? Caption = null, string? MimeType = null, string? Filename = null, bool? Ptt = null, double? Latitude = null, double? Longitude = null, string? DisplayName = null, string? Title = null, string? Reaction = null, string? ReactionTo = null, bool? Edited = null, bool? Unavailable = null, string? UnavailableReason = null, IReadOnlyList<HistoryPollOption>? PollOptions = null, IReadOnlyList<HistoryMedia>? Media = null, HistoryMediaRetrieval? MediaRetrieval = null, [property: JsonPropertyName("whatsapp_id")] string? WhatsAppId = null, CloudOrder? Order = null);
public sealed record HistoryPage<T>(bool Success, IReadOnlyList<T> Data, bool HasMore, string? NextCursor, string? PreviousCursor);
/// <summary>The other party: user ID, phone number or username, as the call reported them.</summary>
public sealed record SessionCallPeer(string? Id = null, string? PhoneNumber = null, string? Username = null);
/// <summary>One call on a number, read from the number's data region.</summary>
public sealed record SessionCallRecord(string CallId, string ProjectId, string SessionId, string Direction, string Upstream, string Outcome, string State, bool HasVideo, SessionCallPeer? Peer, string StartedAt, string? ConnectedAt, string? EndedAt, int? DurationSeconds, string? EndReason);
public sealed record SessionCallsPage(bool Success, IReadOnlyList<SessionCallRecord> Data, string? NextCursor);
/// <summary>Filters a number's calls. Since and Until are ISO 8601 times bounding when a call started.</summary>
public sealed record ListSessionCallsParameters(int? Limit = null, string? Cursor = null, string? Direction = null, string? Outcome = null, string? Since = null, string? Until = null);
public sealed record ListHistoryChatsParameters(int? Limit = null, string? Cursor = null, string? Kind = null, string? ActiveSince = null, string? ActiveBefore = null);
public sealed record ListHistoryMessagesParameters(int? Limit = null, string? Cursor = null, string? Order = null, string? Since = null, string? Until = null, string? Direction = null, string? Types = null);
Loading
Loading