Free, Open Source, Self-Hosted WhatsApp API Gateway
TypeScript apibotgatewayself-hostedwhatsappwhatsapp-apiwhatsapp-automationwhatsapp-botwhatsapp-gatewaywhatsapp-gateway-apiwhatsapp-webwhatsapp-web-api
fix(sdk): gate every exposed payload, fix drifted types
Yudhi Armyndharisa93687671885
diff --git a/docs/18-sdk-design.md b/docs/18-sdk-design.mdindex 537e173da..0ee28d5f4 100644--- a/docs/18-sdk-design.md+++ b/docs/18-sdk-design.md@@ -1173,7 +1173,7 @@ The wire types live in a dedicated module (`types.ts` / `types.py`) so they can**Requests.** Each SDK's test suite mocks the HTTP transport and **asserts on the exact request path, method, and body** — so a drift between an SDK method and the real API (the class of bug that once shipped `messages/text` instead of the real `messages/send-text`) breaks a test rather than reaching users.-**Responses.** That is a different problem, and for a long time nothing covered it — #754 is the proof: the status, label, and channel record types drifted from the engine interface for releases without a single test noticing, because asserting the request says nothing about the reply. `openapi:check` does not cover it either: the schemas of those records (`LabelDto`, `ChannelDto`, `ChannelMessageDto`, `StatusDto` and `StatusListResponseDto`) are in `openapi.json`, but `check:contract-shapes` does not yet map the SDKs' label, channel and status records to them. The gate is now `sdk/javascript/test/wire-contract.test-d.ts` — a type-level test where `tsc --noEmit` (run by `npm test` ahead of vitest) fails if a record type stops matching the engine-neutral shape as it arrives over JSON. Its `Wire*` types are **maintained by hand**: `sdk-ci.yml` re-runs the job when `whatsapp-engine.interface.ts` changes, but keeping the two in step is a human step, not a generated one.+**Responses.** That is a different problem, and for a long time nothing covered it — #754 is the proof: the status, label, and channel record types drifted from the engine interface for releases without a single test noticing, because asserting the request says nothing about the reply. `openapi:check` does not cover it either, because it only keeps the snapshot in step with the code. The schemas of those records (`LabelDto`, `ChannelDto`, `ChannelMessageDto`, `StatusDto` and `StatusListResponseDto`) are in `openapi.json`, and `check:contract-shapes` compares the SDKs' label, channel and status records with them field by field. A second check is `sdk/javascript/test/wire-contract.test-d.ts` — a type-level test where `tsc --noEmit` (run by `npm test` ahead of vitest) fails if a record type stops matching the engine-neutral shape as it arrives over JSON. Its `Wire*` types are **maintained by hand**: `sdk-ci.yml` re-runs the job when `whatsapp-engine.interface.ts` changes, but keeping the two in step is a human step, not a generated one.### Release processdiff --git a/scripts/check-contract-shapes.mjs b/scripts/check-contract-shapes.mjsindex 93e758691..0ad2f46b4 100644--- a/scripts/check-contract-shapes.mjs+++ b/scripts/check-contract-shapes.mjs@@ -43,6 +43,12 @@* allowlist culture of check-audit: an exclusion is a recorded decision, not a silent skip, and* the goal is to shrink it to zero (usually by tightening the hand type; where the CONTRACT* under-describes reality, fix the backend DTO decorator, regenerate, and un-exclude).+ *+ * A mapping only gates the types somebody remembered to list, so a new DTO used to ship ungated by+ * default. The coverage check closes that: every schema an exposed operation sends or returns+ * (request bodies and 2xx responses, nested schemas included, the resources sdk/README.md declares+ * unexposed left out) must be compared by at least one of the JavaScript, Python, Go and Java+ * clients, or be recorded in UNMAPPED_SCHEMAS with a reason. The dashboard does not count towards it.*/import { readFileSync, readdirSync, realpathSync } from 'node:fs';@@ -143,6 +149,37 @@ const MAPPINGS = {WebhookFilterCondition: 'WebhookFilterConditionDto',WebhookRedriveResult: 'WebhookRedriveResultDto',WebhookResponse: 'WebhookResponseDto',+ // Payloads that sat outside every mapping until the coverage check required one.+ CatalogInfo: 'CatalogDto',+ CatalogProduct: 'ProductDto',+ ChannelMessageRecord: 'ChannelMessageDto',+ ChannelRecord: 'ChannelDto',+ ChatPresence: 'ChatPresenceResponseDto',+ CheckNumberResponse: 'NumberCheckResponseDto',+ ClickButtonRequest: 'ClickButtonDto',+ ContactPhoneResponse: 'ResolvedPhoneResponseDto',+ ContactRecord: 'ContactDto',+ ConvertMediaInput: 'ConvertMediaDto',+ ConvertedMedia: 'ConvertedMediaResponseDto',+ GroupSettingsResponse: ['GroupSettingsResponseDto', 'GroupSettingsDto'],+ HealthResponse: 'HealthCheckResponseDto',+ JoinGroupResponse: 'GroupJoinedResponseDto',+ LabelRecord: 'LabelDto',+ MediaConversionAvailability: 'ConversionStatusResponseDto',+ PaginatedProducts: 'PaginatedProductsDto',+ ParticipantResult: 'ParticipantOperationResultDto',+ ParticipantsResult: 'ParticipantsOperationResponseDto',+ ProductMessageResponse: 'ProductMessageResponseDto',+ QrCodeResponse: 'QRCodeResponseDto',+ ReactionRecord: 'MessageReactionDto',+ ReactionSender: 'MessageReactionSenderDto',+ SearchResults: 'SearchResultsResponseDto',+ SessionConfig: 'SessionConfigResponseDto',+ SessionStatsOverview: 'SessionsOverviewResponseDto',+ StatusMediaInput: 'StatusMediaInput',+ StatusRecord: 'StatusDto',+ TemplateRecord: 'TemplateResponseDto',+ WebhookTestResult: 'WebhookTestResponseDto',},'dashboard/src/services/api.ts': {AccountRestriction: 'AccountRestrictionDto',@@ -177,11 +214,11 @@ const MAPPINGS = {* added makes the shrink loud.*/const MINIMUM_MAPPED = {- 'sdk/javascript/src/types.ts': 85,+ 'sdk/javascript/src/types.ts': 117,'dashboard/src/services/api.ts': 22,- 'sdk/python/openwa/types.py': 84,- 'sdk/go': 81,- 'sdk/java': 85,+ 'sdk/python/openwa/types.py': 129,+ 'sdk/go': 130,+ 'sdk/java': 134,};/** Known drift, deliberately not gated yet — each line is a to-adjudicate follow-up. */@@ -197,10 +234,24 @@ const EXCLUDED = {'BY DESIGN: every component is `json:"-"` and MarshalJSON writes the body by hand, because the three fields need an explicit null to reset and Go cannot express "null" and "absent" through one pointer, so the harvester sees no wire fields at all',UpdateSessionProxyRequest:'BY DESIGN, same shape as UpdateSessionConfigRequest above: clearing a proxy needs an explicit null and `omitempty` on a nil pointer omits the key instead, so ProxyURL is `json:"-"` with a ClearProxyURL flag and MarshalJSON writes the body, leaving no wire fields for the harvester to see',+ ContactRecord:+ 'Number is a *string although the contract requires it and the server always sends it; making it a string is a source break for callers that dereference it, so it waits for a breaking release. The other fields conform',+ GroupPictureResponse:+ 'URL is a plain string although the contract types it string|null (null when the group has no picture); a JSON null decodes to the empty string, which is how callers read "no picture", and a *string would be a source break',+ GroupSettings:+ 'memberAddMode is a plain string because this struct is also the PUT body; the defined MemberAddMode type that GroupInfo uses would be a source break for callers that assign a string. The other fields conform',+ MembershipRequestActionRequest:+ 'BY DESIGN: `participants` carries no omitempty so that a non-nil slice always sends the key, empty included, and naming nobody stays a 400 instead of collapsing into the absent key that means every pending request',+ StatusRecord:+ 'Type is a plain string holding text, image, video or voice; a defined type would be a source break for callers that pass it on as a string. The other fields conform',},'sdk/java': {UpdateSessionConfigRequest:'BY DESIGN: the three clear* components are client-side control flags consumed by UpdateSessionConfigRequestSerializer, which is what emits the explicit null; they never reach the wire',+ GroupSettings:+ 'memberAddMode is a String because this record is also the PUT body; the MemberAddMode enum that GroupInfo uses would break callers that pass a string. The other components conform',+ StatusRecord:+ 'type is a String holding text, image, video or voice; an enum would break callers that compare it as a string. The other components conform',},'dashboard/src/services/api.ts': {Webhook:@@ -210,6 +261,34 @@ const EXCLUDED = {},};+const ACK_SHAPE =+ 'every client answers it as the shared SuccessResult {success, message?}, which spans the success-only and the success-plus-message acks, so no single schema fits it';+const INVITE_CODE_SHAPE =+ 'both invite routes are answered as InviteCodeResponse, whose message exists on the revoke route only, so it cannot conform to either schema';++/**+ * Schemas that an exposed operation sends or returns and that no client compares, each with the+ * reason. The coverage check fails on a schema in neither place, and on an entry here that a client+ * now compares (or that no exposed operation uses any more), so the list cannot rot.+ */+const UNMAPPED_SCHEMAS = {+ CallAckResponseDto: ACK_SHAPE,+ ChannelAckResponseDto: ACK_SHAPE,+ ContactAckResponseDto: ACK_SHAPE,+ GroupAckResponseDto: ACK_SHAPE,+ GroupInviteCodeResponseDto: INVITE_CODE_SHAPE,+ GroupInviteCodeRevokedResponseDto: INVITE_CODE_SHAPE,+ LabelAckResponseDto: ACK_SHAPE,+ LivenessResponseDto:+ 'GET /health/live answers {status}, which JavaScript, Python and Go read as an inline map and Java as the HealthResponse of GET /health',+ MessageActionResponseDto: ACK_SHAPE,+ ProfileAckResponseDto: ACK_SHAPE,+ SessionActionResponseDto: ACK_SHAPE,+ SessionGroupSummaryDto:+ 'GET /groups is read as GroupSummary, the shape the create route answers, which also carries a participantsCount and an isAdmin that a listing never sends',+ StatusDeletedResponseDto: 'every client discards the {message} body of DELETE status and returns nothing',+};+// UpdateWebhookRequest is mapped on the three clients that declare it as a named type. The// JavaScript SDK spells it `Partial<CreateWebhookRequest> & { active?: boolean }`, a type ALIAS// rather than an interface, which the hand parser does not read; mapping it there would fail as a@@ -303,6 +382,50 @@ const PYTHON_MAPPING = {WebhookFilters: 'WebhookFiltersDto',WebhookRedriveResult: 'WebhookRedriveResultDto',WebhookResponse: 'WebhookResponseDto',+ // Payloads that sat outside every mapping until the coverage check required one.+ BatchError: 'BatchMessageErrorDto',+ BulkOptions: 'BulkMessageOptionsDto',+ CatalogInfo: 'CatalogDto',+ CatalogProduct: 'ProductDto',+ ChannelMessageRecord: 'ChannelMessageDto',+ ChannelRecord: 'ChannelDto',+ ChatHistoryMedia: 'ChatHistoryMediaDto',+ ChatHistoryPoll: 'ChatHistoryPollDto',+ ChatPresence: 'ChatPresenceResponseDto',+ CheckNumberResponse: 'NumberCheckResponseDto',+ ClickButtonRequest: 'ClickButtonDto',+ ContactPhoneResponse: 'ResolvedPhoneResponseDto',+ ContactRecord: 'ContactDto',+ ConvertedMedia: 'ConvertedMediaResponseDto',+ GroupSettings: ['GroupSettingsResponseDto', 'GroupSettingsDto'],+ HealthResponse: 'HealthCheckResponseDto',+ JoinGroupResponse: 'GroupJoinedResponseDto',+ LabelRecord: 'LabelDto',+ MediaConversionAvailability: 'ConversionStatusResponseDto',+ MemoryUsage: 'SessionMemoryUsageDto',+ MessageCall: 'ChatHistoryCallDto',+ MessageContact: 'ChatHistoryContactDto',+ MessageLocation: 'ChatHistoryLocationDto',+ MessageOrder: 'ChatHistoryOrderDto',+ MessageProduct: 'ChatHistoryProductDto',+ PaginatedProducts: 'PaginatedProductsDto',+ ParticipantResult: 'ParticipantOperationResultDto',+ ParticipantsResult: 'ParticipantsOperationResponseDto',+ ProductMessageResponse: 'ProductMessageResponseDto',+ ProductPagination: 'ProductPaginationDto',+ QrCodeResponse: 'QRCodeResponseDto',+ QuotedMessage: 'ChatHistoryQuotedMessageDto',+ ReactionRecord: 'MessageReactionDto',+ ReactionSender: 'MessageReactionSenderDto',+ SearchResults: 'SearchResultsResponseDto',+ SessionConfig: 'SessionConfigResponseDto',+ SessionStatsOverview: 'SessionsOverviewResponseDto',+ StatusContact: 'StatusContactDto',+ StatusMediaInput: 'StatusMediaInput',+ StatusRecord: 'StatusDto',+ TemplateRecord: 'TemplateResponseDto',+ UpdateTemplateRequest: 'UpdateTemplateDto',+ WebhookTestResult: 'WebhookTestResponseDto',};/** Go client pairs (wire structs across types_*.go). */@@ -390,6 +513,54 @@ const GO_MAPPING = {WebhookDeliveryFailure: 'WebhookDeliveryFailureDto',WebhookRedriveResult: 'WebhookRedriveResultDto',WebhookResponse: 'WebhookResponseDto',+ // Payloads that sat outside every mapping until the coverage check required one.+ BatchError: 'BatchMessageErrorDto',+ BulkOptions: 'BulkMessageOptionsDto',+ CatalogInfo: 'CatalogDto',+ CatalogProduct: 'ProductDto',+ ChannelMessageRecord: 'ChannelMessageDto',+ ChannelRecord: 'ChannelDto',+ ChatHistoryMedia: 'ChatHistoryMediaDto',+ ChatHistoryPoll: 'ChatHistoryPollDto',+ ChatPresence: 'ChatPresenceResponseDto',+ CheckNumberResponse: 'NumberCheckResponseDto',+ ClickButtonRequest: 'ClickButtonDto',+ ContactPhoneResponse: 'ResolvedPhoneResponseDto',+ ContactRecord: 'ContactDto',+ ConvertMediaInput: 'ConvertMediaDto',+ ConvertedMedia: 'ConvertedMediaResponseDto',+ GroupPictureResponse: 'GroupPictureResponseDto',+ GroupSettings: ['GroupSettingsResponseDto', 'GroupSettingsDto'],+ HealthResponse: 'HealthCheckResponseDto',+ JoinGroupResponse: 'GroupJoinedResponseDto',+ LabelRecord: 'LabelDto',+ MediaConversionAvailability: 'ConversionStatusResponseDto',+ MembershipRequestActionRequest: 'MembershipRequestActionDto',+ MemoryUsage: 'SessionMemoryUsageDto',+ MessageCall: 'ChatHistoryCallDto',+ MessageContact: 'ChatHistoryContactDto',+ MessageLocation: 'ChatHistoryLocationDto',+ MessageOrder: 'ChatHistoryOrderDto',+ MessageProduct: 'ChatHistoryProductDto',+ PaginatedProducts: 'PaginatedProductsDto',+ ParticipantResult: 'ParticipantOperationResultDto',+ ParticipantsResult: 'ParticipantsOperationResponseDto',+ ProductMessageResponse: 'ProductMessageResponseDto',+ ProductPagination: 'ProductPaginationDto',+ QrCodeResponse: 'QRCodeResponseDto',+ QuotedMessage: 'ChatHistoryQuotedMessageDto',+ ReactionRecord: 'MessageReactionDto',+ ReactionSender: 'MessageReactionSenderDto',+ SearchResults: 'SearchResultsResponseDto',+ SessionConfig: 'SessionConfigResponseDto',+ SessionStatsOverview: 'SessionsOverviewResponseDto',+ StatusContact: 'StatusContactDto',+ StatusListResponse: 'StatusListResponseDto',+ StatusMediaInput: 'StatusMediaInput',+ StatusRecord: 'StatusDto',+ TemplateRecord: 'TemplateResponseDto',+ UpdateTemplateRequest: 'UpdateTemplateDto',+ WebhookTestResult: 'WebhookTestResponseDto',};/** Java client pairs (record components in model/*.java). */@@ -481,6 +652,54 @@ const JAVA_MAPPING = {WebhookDeliveryFailure: 'WebhookDeliveryFailureDto',WebhookRedriveResult: 'WebhookRedriveResultDto',WebhookResponse: 'WebhookResponseDto',+ // Payloads that sat outside every mapping until the coverage check required one.+ BatchError: 'BatchMessageErrorDto',+ Call: 'ChatHistoryCallDto',+ CatalogInfo: 'CatalogDto',+ CatalogProduct: 'ProductDto',+ ChannelMessageRecord: 'ChannelMessageDto',+ ChannelRecord: 'ChannelDto',+ ChatPresence: 'ChatPresenceResponseDto',+ CheckNumberResponse: 'NumberCheckResponseDto',+ ClickButtonRequest: 'ClickButtonDto',+ Contact: 'ChatHistoryContactDto',+ ContactPhoneResponse: 'ResolvedPhoneResponseDto',+ ContactRecord: 'ContactDto',+ ConvertMediaRequest: 'ConvertMediaDto',+ ConvertedMedia: 'ConvertedMediaResponseDto',+ GroupPictureResponse: 'GroupPictureResponseDto',+ GroupSettings: ['GroupSettingsResponseDto', 'GroupSettingsDto'],+ HealthResponse: 'HealthCheckResponseDto',+ JoinGroupResponse: 'GroupJoinedResponseDto',+ LabelRecord: 'LabelDto',+ Location: 'ChatHistoryLocationDto',+ Media: 'ChatHistoryMediaDto',+ MediaConversionAvailability: 'ConversionStatusResponseDto',+ MembershipRequestActionRequest: 'MembershipRequestActionDto',+ MemoryUsage: 'SessionMemoryUsageDto',+ Options: 'BulkMessageOptionsDto',+ Order: 'ChatHistoryOrderDto',+ PaginatedProducts: 'PaginatedProductsDto',+ Pagination: 'ProductPaginationDto',+ ParticipantResult: 'ParticipantOperationResultDto',+ ParticipantsResult: 'ParticipantsOperationResponseDto',+ Poll: 'ChatHistoryPollDto',+ Product: 'ChatHistoryProductDto',+ ProductMessageResponse: 'ProductMessageResponseDto',+ QrCodeResponse: 'QRCodeResponseDto',+ QuotedMessage: 'ChatHistoryQuotedMessageDto',+ ReactionRecord: 'MessageReactionDto',+ ReactionSender: 'MessageReactionSenderDto',+ SearchResults: 'SearchResultsResponseDto',+ SessionConfig: 'SessionConfigResponseDto',+ SessionStatsOverview: 'SessionsOverviewResponseDto',+ StatusContact: 'StatusContactDto',+ StatusListResult: 'StatusListResponseDto',+ StatusMediaInput: 'StatusMediaInput',+ StatusRecord: 'StatusDto',+ TemplateRecord: 'TemplateResponseDto',+ UpdateTemplateRequest: 'UpdateTemplateDto',+ WebhookTestResult: 'WebhookTestResponseDto',};// ── hand-type parsing (declarations follow the regular formatting of the two files) ──@@ -1103,6 +1322,81 @@ export function parseJavaTypes(sources) {return records;}+// ── schema coverage: nothing an exposed operation sends or returns goes unmapped by default ──++/**+ * The resources sdk/README.md declares deliberately unexposed, read from the README rather than+ * restated here, the way check-sdk-coverage.mjs reads it: a hand-copied second list is what drifts.+ */+export function unexposedResources(readme) {+ const start = readme.indexOf('Deliberately **not** exposed');+ const end = readme.indexOf('Everything else the gateway publishes', start);+ if (start < 0 || end < 0) {+ throw new Error(+ 'sdk/README.md: could not find the "Deliberately not exposed" paragraph, so the schema coverage check cannot derive its scope.',+ );+ }+ const names = [...readme.slice(start, end).matchAll(/`([^`]+)`/g)].map(m => m[1].split('/')[0].trim());+ if (names.length < 8) {+ throw new Error(`sdk/README.md: parsed only ${names.length} unexposed resources, expected the full list.`);+ }+ return new Set(names);+}++/**+ * Every schema an exposed operation sends or returns, nested ones included: request bodies and 2xx+ * responses only, so the shared error envelope is not asked for. A nested schema counts because a+ * parent's complex field is compared by presence only, which leaves the nested shape ungated.+ */+export function exposedSchemas(openapi, unexposed) {+ const seen = new Set();+ const visit = node => {+ if (!node || typeof node !== 'object') return;+ if (typeof node.$ref === 'string') {+ const name = /^#\/components\/schemas\/(.+)$/.exec(node.$ref)?.[1];+ if (!name || seen.has(name)) return;+ seen.add(name);+ visit(openapi.components.schemas[name]);+ return;+ }+ Object.values(node).forEach(visit);+ };+ for (const [path, item] of Object.entries(openapi.paths)) {+ const shape = path.replace(/\{[^}]*\}/g, '*');+ const resource = /^\/api\/sessions\/\*\/([^/]+)/.exec(shape)?.[1] ?? /^\/api\/([^/*]+)/.exec(shape)?.[1] ?? '';+ if (unexposed.has(resource) || unexposed.has(resource.replace(/-rules$/, ''))) continue;+ for (const operation of Object.values(item)) {+ if (!operation || typeof operation !== 'object') continue;+ visit(operation.requestBody);+ for (const [status, response] of Object.entries(operation.responses ?? {})) {+ if (status.startsWith('2')) visit(response);+ }+ }+ }+ return seen;+}++/**+ * What stands between the exposed schemas and a green run: a schema no client compares and+ * UNMAPPED_SCHEMAS does not record, and a record that no longer describes anything.+ */+export function schemaCoverageProblems(exposed, compared, unmapped) {+ const problems = [];+ for (const name of [...exposed].sort()) {+ if (!compared.has(name) && !(name in unmapped)) {+ problems.push(+ `${name} is sent or returned by the SDKs but no client compares it and UNMAPPED_SCHEMAS does not record it`,+ );+ }+ }+ for (const name of Object.keys(unmapped)) {+ if (!exposed.has(name)) problems.push(`UNMAPPED_SCHEMAS lists ${name}, which no exposed operation uses: remove it`);+ else if (compared.has(name))+ problems.push(`UNMAPPED_SCHEMAS lists ${name}, which a client now compares: remove it`);+ }+ return problems;+}+// ── CLI driver ──// Resolved-path comparison, not a basename match: splitting on `/` finds no separator in a Windows@@ -1140,6 +1434,7 @@ if (isDirectRun) {excluded: EXCLUDED[file] ?? {},floor: MINIMUM_MAPPED[file],compareOptionality: true,+ sdk: file.startsWith('sdk/'),})),{label: 'sdk/python/openwa/types.py',@@ -1148,6 +1443,7 @@ if (isDirectRun) {excluded: EXCLUDED['sdk/python/openwa/types.py'] ?? {},floor: MINIMUM_MAPPED['sdk/python/openwa/types.py'],compareOptionality: true,+ sdk: true,},{label: 'sdk/go (types_*.go)',@@ -1156,6 +1452,7 @@ if (isDirectRun) {excluded: EXCLUDED['sdk/go'] ?? {},floor: MINIMUM_MAPPED['sdk/go'],compareOptionality: true,+ sdk: true,},{label: 'sdk/java (model/*.java)',@@ -1164,6 +1461,7 @@ if (isDirectRun) {excluded: EXCLUDED['sdk/java'] ?? {},floor: MINIMUM_MAPPED['sdk/java'],compareOptionality: false,+ sdk: true,},];@@ -1175,26 +1473,30 @@ if (isDirectRun) {let fileCompared = 0;const fileResults = [];- for (const [handName, schemaName] of Object.entries(client.mapping)) {+ for (const [handName, target] of Object.entries(client.mapping)) {if (client.excluded[handName]) continue;const hand = handTypes[handName];- const schema = schemas[schemaName];if (!hand) {fileResults.push(` MISSING hand type ${handName} (declared in mapping but not found in ${client.label})`);failures++;continue;}- if (!schema) {- fileResults.push(` MISSING schema ${schemaName} (declared in mapping but not in openapi.json)`);- failures++;- continue;- }- fileCompared++;- compared++;- const diffs = comparePair(handName, hand, schemaName, schema, schemas, client.compareOptionality);- if (diffs.length) {- fileResults.push(` ${handName} ↔ ${schemaName}:`, ...diffs.map(d => ` ${d}`));- failures++;+ // A list maps one hand type to several schemas: a body type that is also the response has to+ // conform to each of them.+ for (const schemaName of [target].flat()) {+ const schema = schemas[schemaName];+ if (!schema) {+ fileResults.push(` MISSING schema ${schemaName} (declared in mapping but not in openapi.json)`);+ failures++;+ continue;+ }+ fileCompared++;+ compared++;+ const diffs = comparePair(handName, hand, schemaName, schema, schemas, client.compareOptionality);+ if (diffs.length) {+ fileResults.push(` ${handName} ↔ ${schemaName}:`, ...diffs.map(d => ` ${d}`));+ failures++;+ }}}@@ -1216,9 +1518,22 @@ if (isDirectRun) {}}+ const exposed = exposedSchemas(openapi, unexposedResources(readFileSync(`${REPO_ROOT}sdk/README.md`, 'utf8')));+ const comparedSchemas = new Set(+ CLIENTS.filter(c => c.sdk)+ .flatMap(c => Object.entries(c.mapping).filter(([handName]) => !c.excluded[handName]))+ .flatMap(([, target]) => [target].flat()),+ );+ const uncovered = schemaCoverageProblems(exposed, comparedSchemas, UNMAPPED_SCHEMAS);+ console.log(+ `schema coverage: ${exposed.size} schemas sent or returned, ${Object.keys(UNMAPPED_SCHEMAS).length} recorded unmapped in UNMAPPED_SCHEMAS, ${uncovered.length ? 'FAILURES' : 'all covered'}`,+ );+ for (const line of uncovered) console.log(` ${line}`);+ failures += uncovered.length;+console.log(failures- ? `\ncheck-contract-shapes: ${failures} failing pair(s) — the contract side wins; tighten the hand type or fix the backend DTO and regenerate.`+ ? `\ncheck-contract-shapes: ${failures} failure(s) — the contract side wins; tighten the hand type or fix the backend DTO and regenerate.`: `\ncheck-contract-shapes: ${compared} pairs conform.`,);process.exit(failures ? 1 : 0);diff --git a/scripts/check-contract-shapes.spec.mjs b/scripts/check-contract-shapes.spec.mjsindex 37268243d..a37c52da9 100644--- a/scripts/check-contract-shapes.spec.mjs+++ b/scripts/check-contract-shapes.spec.mjs@@ -11,19 +11,22 @@import { test } from 'node:test';import assert from 'node:assert/strict';import { spawnSync } from 'node:child_process';-import { mkdtempSync, rmSync, symlinkSync } from 'node:fs';+import { mkdtempSync, readFileSync, rmSync, symlinkSync } from 'node:fs';import { tmpdir } from 'node:os';import { join } from 'node:path';import { fileURLToPath } from 'node:url';import {comparePair,+ exposedSchemas,handToken,parseGoTypes,parseHandTypes,parseJavaTypes,parseObjectToken,parsePythonTypes,+ schemaCoverageProblems,schemaToken,+ unexposedResources,} from './check-contract-shapes.mjs';const handSource = `@@ -341,7 +344,81 @@ test('a run through a symlinked path still reports', () => {encoding: 'utf8',});assert.match(run.stdout + run.stderr, /pairs compared/);+ assert.match(run.stdout + run.stderr, /schema coverage: \d+ schemas/);} finally {rmSync(dir, { recursive: true, force: true });}});++const ref = name => ({ $ref: `#/components/schemas/${name}` });+const json = schema => ({ content: { 'application/json': { schema } } });+const coverageSpec = {+ paths: {+ '/api/sessions/{sessionId}/labels': {+ parameters: [{ name: 'sessionId', in: 'path' }],+ get: { responses: { 200: json({ type: 'array', items: ref('LabelDto') }), 400: json(ref('ErrorResponse')) } },+ },+ '/api/sessions/{sessionId}/status': {+ post: {+ requestBody: json(ref('PostDto')),+ responses: { 201: json(ref('StatusResultDto')), 404: { $ref: '#/components/responses/NotFound' } },+ },+ },+ '/api/audit': { get: { responses: { 200: json(ref('AuditDto')) } } },+ },+ components: {+ schemas: {+ LabelDto: { type: 'object', properties: { hexColor: { type: 'string' } } },+ PostDto: { type: 'object', properties: { text: { type: 'string' } } },+ StatusResultDto: { type: 'object', properties: { contact: { allOf: [ref('ContactDto')] } } },+ ContactDto: { type: 'object', properties: { id: { type: 'string' } } },+ ErrorResponse: { type: 'object', properties: { detail: ref('ErrorDetail') } },+ ErrorDetail: { type: 'object', properties: {} },+ AuditDto: { type: 'object', properties: {} },+ },+ },+};++test('exposedSchemas follows nested refs from bodies and 2xx responses only, inside the exposed resources', () => {+ // ContactDto is only reachable through StatusResultDto.contact: a nested shape is ungated unless it is+ // asked for too. The error envelope, a resource the README leaves out and a non-schema ref are not.+ const found = exposedSchemas(coverageSpec, new Set(['audit']));+ assert.deepEqual([...found].sort(), ['ContactDto', 'LabelDto', 'PostDto', 'StatusResultDto']);+});++test('schemaCoverageProblems fails when the mapping that held a schema is deleted', () => {+ const exposed = exposedSchemas(coverageSpec, new Set(['audit']));+ const compared = new Set(['LabelDto', 'PostDto', 'StatusResultDto', 'ContactDto']);+ assert.deepEqual(schemaCoverageProblems(exposed, compared, {}), []);+ compared.delete('LabelDto');+ const problems = schemaCoverageProblems(exposed, compared, {});+ assert.equal(problems.length, 1);+ assert.match(problems[0], /^LabelDto .*no client compares it/);+});++test('schemaCoverageProblems accepts a recorded schema and rejects a record that went stale', () => {+ const exposed = new Set(['AckDto', 'LabelDto']);+ const compared = new Set(['LabelDto']);+ assert.deepEqual(schemaCoverageProblems(exposed, compared, { AckDto: 'shared ack type' }), []);+ const stale = schemaCoverageProblems(exposed, compared, { AckDto: 'x', LabelDto: 'x', GoneDto: 'x' });+ assert.equal(stale.length, 2);+ assert.ok(stale.some(p => /LabelDto.*now compares/.test(p)));+ assert.ok(stale.some(p => /GoneDto.*no exposed operation/.test(p)));+});++test('unexposedResources reads the README paragraph and refuses a README it cannot read', () => {+ const names = ['docs', 'auth/*', 'audit', 'settings', 'stats', 'automation', 'infra', 'plugins'];+ const readme = `> Deliberately **not** exposed: ${names.map(n => `\`${n}\``).join(', ')}.\n> Everything else the gateway publishes is exposed.`;+ assert.deepEqual(+ [...unexposedResources(readme)],+ ['docs', 'auth', 'audit', 'settings', 'stats', 'automation', 'infra', 'plugins'],+ );+ assert.throws(() => unexposedResources('no such paragraph'), /Deliberately not exposed/);+ assert.throws(+ () => unexposedResources('Deliberately **not** exposed: `docs`. Everything else the gateway publishes'),+ /only 1/,+ );+ // The real README must still parse, or the coverage check has lost its scope.+ const real = readFileSync(fileURLToPath(new URL('../sdk/README.md', import.meta.url)), 'utf8');+ assert.ok(unexposedResources(real).has('audit'));+});diff --git a/sdk/go/types.go b/sdk/go/types.goindex f63bae6bd..03d7fdd86 100644--- a/sdk/go/types.go+++ b/sdk/go/types.go@@ -40,7 +40,7 @@ type ParticipantResult struct {// per-participant outcome in Results, so Success alone hides a member that was rejected.type ParticipantsResult struct {Success bool `json:"success"`- Message string `json:"message,omitempty"`+ Message string `json:"message"`Results []ParticipantResult `json:"results"`}diff --git a/sdk/go/types_catalog.go b/sdk/go/types_catalog.goindex e17994422..772771030 100644--- a/sdk/go/types_catalog.go+++ b/sdk/go/types_catalog.go@@ -7,8 +7,8 @@ type CatalogInfo struct {ID string `json:"id"`Name string `json:"name"`Description *string `json:"description,omitempty"`- ProductCount int `json:"productCount,omitempty"`- URL string `json:"url,omitempty"`+ ProductCount int `json:"productCount"`+ URL string `json:"url"`}// CatalogProductsQuery paginates the catalog products list.@@ -35,8 +35,8 @@ type CatalogProduct struct {Currency string `json:"currency,omitempty"`PriceFormatted string `json:"priceFormatted,omitempty"`ImageURL *string `json:"imageUrl,omitempty"`- URL string `json:"url,omitempty"`- IsAvailable bool `json:"isAvailable,omitempty"`+ URL string `json:"url"`+ IsAvailable bool `json:"isAvailable"`RetailerID string `json:"retailerId,omitempty"`}diff --git a/sdk/go/types_contact.go b/sdk/go/types_contact.goindex 229cf98ff..0f119f18f 100644--- a/sdk/go/types_contact.go+++ b/sdk/go/types_contact.go@@ -15,8 +15,8 @@ type ContactRecord struct {Name *string `json:"name,omitempty"`Number *string `json:"number,omitempty"`PushName *string `json:"pushName,omitempty"`- IsMyContact bool `json:"isMyContact,omitempty"`- IsBlocked bool `json:"isBlocked,omitempty"`+ IsMyContact bool `json:"isMyContact"`+ IsBlocked bool `json:"isBlocked"`ProfilePicURL *string `json:"profilePicUrl,omitempty"`}@@ -24,7 +24,7 @@ type ContactRecord struct {type CheckNumberResponse struct {Number string `json:"number"`Exists bool `json:"exists"`- WhatsappID *string `json:"whatsappId,omitempty"`+ WhatsappID *string `json:"whatsappId"`}// ProfilePictureResponse carries a contact's profile picture URL.@@ -41,7 +41,7 @@ type ProfilePicturesResponse struct {// ContactPhoneResponse resolves a contact's phone number.type ContactPhoneResponse struct {ContactID string `json:"contactId"`- Phone *string `json:"phone,omitempty"`+ Phone *string `json:"phone"`}// ListContactsQuery paginates the contact list.diff --git a/sdk/go/types_message.go b/sdk/go/types_message.goindex 5af7e803f..d64e32265 100644--- a/sdk/go/types_message.go+++ b/sdk/go/types_message.go@@ -270,7 +270,7 @@ type MessageListResponse struct {// ChatHistoryMedia is the media block on a live history message.type ChatHistoryMedia struct {- Mimetype string `json:"mimetype,omitempty"`+ Mimetype string `json:"mimetype"`Filename string `json:"filename,omitempty"`Data string `json:"data,omitempty"`Omitted bool `json:"omitted,omitempty"`@@ -279,14 +279,14 @@ type ChatHistoryMedia struct {// QuotedMessage is the quoted-message block on a live history message.type QuotedMessage struct {- ID string `json:"id,omitempty"`- Body string `json:"body,omitempty"`+ ID string `json:"id"`+ Body string `json:"body"`}// MessageLocation is the location block on a live history message.type MessageLocation struct {- Latitude float64 `json:"latitude,omitempty"`- Longitude float64 `json:"longitude,omitempty"`+ Latitude float64 `json:"latitude"`+ Longitude float64 `json:"longitude"`Description string `json:"description,omitempty"`Address string `json:"address,omitempty"`URL string `json:"url,omitempty"`@@ -451,8 +451,8 @@ type BulkMessageResponse struct {// BatchError is a per-message failure in a batch result.type BatchError struct {- Code string `json:"code,omitempty"`- Message string `json:"message,omitempty"`+ Code string `json:"code"`+ Message string `json:"message"`}// BatchMessageStatus is one recipient's send outcome inside a batch.diff --git a/sdk/go/types_misc.go b/sdk/go/types_misc.goindex ea34ee75c..1eb96d628 100644--- a/sdk/go/types_misc.go+++ b/sdk/go/types_misc.go@@ -5,7 +5,7 @@ package openwa// HealthResponse is the /health payload.type HealthResponse struct {Status string `json:"status"`- Timestamp string `json:"timestamp,omitempty"`+ Timestamp string `json:"timestamp"`Version string `json:"version,omitempty"`}@@ -74,7 +74,7 @@ type UpdateTemplateRequest struct {type LabelRecord struct {ID string `json:"id"`Name string `json:"name"`- HexColor string `json:"hexColor,omitempty"`+ HexColor string `json:"hexColor"`}// AddLabelRequest applies a label to a chat.diff --git a/sdk/go/types_session.go b/sdk/go/types_session.goindex 69ed217f2..3c212f8ce 100644--- a/sdk/go/types_session.go+++ b/sdk/go/types_session.go@@ -256,7 +256,7 @@ type SessionStatsOverview struct {Active int `json:"active"`Ready int `json:"ready"`Disconnected int `json:"disconnected"`- ByStatus map[string]int `json:"byStatus,omitempty"`+ ByStatus map[string]int `json:"byStatus"`MemoryUsage MemoryUsage `json:"memoryUsage"`}diff --git a/sdk/go/types_status.go b/sdk/go/types_status.goindex 203314bd7..cb244aec3 100644--- a/sdk/go/types_status.go+++ b/sdk/go/types_status.go@@ -13,7 +13,7 @@ type StatusContact struct {type StatusRecord struct {ID string `json:"id"`Contact StatusContact `json:"contact"`- Type string `json:"type,omitempty"`+ Type string `json:"type"`Caption string `json:"caption,omitempty"`MediaURL string `json:"mediaUrl,omitempty"`BackgroundColor string `json:"backgroundColor,omitempty"`diff --git a/sdk/javascript/src/types.ts b/sdk/javascript/src/types.tsindex 4de14ca32..9a94e2f1b 100644--- a/sdk/javascript/src/types.ts+++ b/sdk/javascript/src/types.ts@@ -49,7 +49,9 @@ export interface ParticipantResult {* The group membership writes. A partial refusal does NOT fail the batch — the request answers 200* and reports the per-participant outcome here, so `success` alone hides a member that was rejected.*/-export interface ParticipantsResult extends SuccessResult {+export interface ParticipantsResult {+ success: boolean;+ message: string;results: ParticipantResult[];}@@ -234,7 +236,7 @@ export interface SessionStatsOverview {ready: number;disconnected: number;byStatus: Record<string, number>;- memoryUsage?: { heapUsed: number; heapTotal: number; rss: number };+ memoryUsage: { heapUsed: number; heapTotal: number; rss: number };}// ── Message ───────────────────────────────────────────────────────@@ -755,29 +757,33 @@ export type BatchLifecycleStatus = 'pending' | 'processing' | 'completed' | 'faiexport interface ContactRecord {id: Jid;- name?: string | null;- number?: string | null;+ /** The name from the account's own addressbook. Absent for a contact that was never saved. */+ name?: string;+ /** MSISDN digits, without a leading + or any separators. */+ number: string;/** The name the contact set on their own account. Both engines emit this as `pushName`. */- pushName?: string | null;- isMyContact?: boolean;+ pushName?: string;+ /** Whether the entry exists in the account's addressbook. */+ isMyContact: boolean;/*** Whether the account has blocked this contact. Reflects the account's real blocklist on both* engines. When the blocklist query fails the field stays at its default rather than reporting* "nobody is blocked", and the gateway logs a warning — so a `false` is not proof the contact is* unblocked if the link is unhealthy.*/- isBlocked?: boolean;+ isBlocked: boolean;/*** A cached picture URL. Only Baileys can fill it (whatsapp-web.js never sets it) and it is often* absent there too, so its absence does not say whether the contact has a picture.*/- profilePicUrl?: string | null;+ profilePicUrl?: string;}export interface CheckNumberResponse {number: string;exists: boolean;- whatsappId?: string | null;+ /** The canonical chat id in the engine's native format, or `null` when the number is not registered. */+ whatsappId: string | null;}export interface ProfilePictureResponse {@@ -1276,7 +1282,7 @@ export interface SendVoiceStatusRequest {export interface HealthResponse {status: string;- timestamp?: string;+ timestamp: string;version?: string;}@@ -1387,7 +1393,7 @@ export interface SubscribeChannelRequest {export interface CatalogInfo {id: string;name: string;- description?: string | null;+ description?: string;/** Counts at most the first 51 products on Baileys. */productCount: number;url: string;@@ -1403,13 +1409,13 @@ export interface CatalogProductsQuery {export interface CatalogProduct {id: string;name: string;- description?: string | null;+ description?: string;/** Absent when the product has no price. */price?: number;currency?: string;/** Absent when `price` is. */priceFormatted?: string;- imageUrl?: string | null;+ imageUrl?: string;url: string;isAvailable: boolean;retailerId?: string;diff --git a/sdk/python/openwa/types.py b/sdk/python/openwa/types.pyindex e5000f8e4..ea61ae6bc 100644--- a/sdk/python/openwa/types.py+++ b/sdk/python/openwa/types.py@@ -130,7 +130,7 @@ class SuccessResult(TypedDict, total=False):message: str-class ParticipantResult(TypedDict, total=False):+class ParticipantResult(TypedDict):"""One entry per requested participant, in the order they were requested.``success`` is true only when the engine confirmed the change for this participant. Engines that@@ -140,17 +140,19 @@ class ParticipantResult(TypedDict, total=False):id: strsuccess: bool- status: int- message: str+ status: NotRequired[int]+ message: NotRequired[str]-class ParticipantsResult(SuccessResult):+class ParticipantsResult(TypedDict):"""The group membership writes.A partial refusal does NOT fail the batch — the request answers 200 and reports theper-participant outcome in ``results``, so ``success`` alone hides a member that was rejected."""+ success: bool+ message: strresults: list[ParticipantResult]@@ -164,13 +166,13 @@ class ParticipantPresence(TypedDict):lastSeen: NotRequired[int]-class ChatPresence(TypedDict, total=False):+class ChatPresence(TypedDict):"""The last presence reported for a chat since it was subscribed."""chatId: strparticipants: list[ParticipantPresence]# Online member count, groups only.- groupOnlineCount: int+ groupOnlineCount: NotRequired[int]# When the gateway received the report -- NOT a WhatsApp timestamp.observedAt: str@@ -335,7 +337,7 @@ class MemoryUsage(TypedDict):rss: int-class SessionStatsOverview(TypedDict, total=False):+class SessionStatsOverview(TypedDict):total: intactive: intready: int@@ -531,28 +533,29 @@ MessageRecord = TypedDict()-class ChatHistoryMedia(TypedDict, total=False):+class ChatHistoryMedia(TypedDict):mimetype: str- filename: str- data: str # base64; absent when the payload was omitted (too large)- omitted: bool- sizeBytes: int+ filename: NotRequired[str]+ # base64; absent when the payload was omitted (too large)+ data: NotRequired[str]+ omitted: NotRequired[bool]+ sizeBytes: NotRequired[int]-class QuotedMessage(TypedDict, total=False):+class QuotedMessage(TypedDict):id: strbody: str-class MessageLocation(TypedDict, total=False):+class MessageLocation(TypedDict):latitude: floatlongitude: float- description: str- address: str- url: str+ description: NotRequired[str]+ address: NotRequired[str]+ url: NotRequired[str]-class MessageCall(TypedDict, total=False):+class MessageCall(TypedDict):"""Call block on a live history message, present on ``call`` messages only."""video: bool@@ -646,13 +649,13 @@ class MessageListResponse(TypedDict):total: int-class ReactionSender(TypedDict, total=False):+class ReactionSender(TypedDict):senderId: Jidemoji: strtimestamp: int-class ReactionRecord(TypedDict, total=False):+class ReactionRecord(TypedDict):"""One emoji and everyone who reacted with it (server returns MessageReaction[])."""emoji: str@@ -705,7 +708,7 @@ class BulkMessageResponse(TypedDict):statusUrl: str-class BatchError(TypedDict, total=False):+class BatchError(TypedDict):code: strmessage: str@@ -751,7 +754,7 @@ class BatchCancelResponse(TypedDict):# ── Contact ───────────────────────────────────────────────────────-class ContactRecord(TypedDict, total=False):+class ContactRecord(TypedDict):"""A contact as the gateway returns it.``isBlocked`` reflects the account's real blocklist on both engines. When the blocklist query@@ -763,12 +766,12 @@ class ContactRecord(TypedDict, total=False):"""id: Jid- name: str | None- number: str | None- pushName: str | None+ name: NotRequired[str]+ number: str+ pushName: NotRequired[str]isMyContact: boolisBlocked: bool- profilePicUrl: str | None+ profilePicUrl: NotRequired[str]class CheckNumberResponse(TypedDict):@@ -866,7 +869,7 @@ class JoinGroupRequest(TypedDict):inviteCode: str-class JoinGroupResponse(TypedDict, total=False):+class JoinGroupResponse(TypedDict):success: boolgroupId: Jid@@ -967,10 +970,10 @@ class WebhookResponse(TypedDict):# NOTE: the server deliberately omits ``secret`` and ``headers`` from reads.-class WebhookTestResult(TypedDict, total=False):+class WebhookTestResult(TypedDict):success: bool- statusCode: int- error: str+ statusCode: NotRequired[int]+ error: NotRequired[str]class WebhookDelivery(TypedDict):@@ -1098,26 +1101,26 @@ class DeleteChatRequest(TypedDict):# ── Status / Stories ──────────────────────────────────────────────-class StatusContact(TypedDict, total=False):+class StatusContact(TypedDict):"""Whose story a :class:`StatusRecord` belongs to."""id: Jid- name: str- pushName: str+ name: NotRequired[str]+ pushName: NotRequired[str]# One status/story from the GET status endpoints (``list``/``from_contact``), which# answer a ``{"statuses": [...]}`` envelope. Mirrors the backend ``Status`` — the engine# payload is returned as-is, with no DTO in between. ``timestamp``/``expiresAt`` are# ISO 8601 strings (``Date`` on the server, serialized).-class StatusRecord(TypedDict, total=False):+class StatusRecord(TypedDict):id: strcontact: StatusContact- type: str- caption: str- mediaUrl: str- backgroundColor: str- font: int+ type: Literal["text", "image", "video", "voice"]+ caption: NotRequired[str]+ mediaUrl: NotRequired[str]+ backgroundColor: NotRequired[str]+ font: NotRequired[int]timestamp: strexpiresAt: str@@ -1280,10 +1283,10 @@ class SendVoiceStatusRequest(TypedDict):# ── Health ────────────────────────────────────────────────────────-class HealthResponse(TypedDict, total=False):+class HealthResponse(TypedDict):status: strtimestamp: str- version: str+ version: NotRequired[str]class HealthDependencyStatus(TypedDict):@@ -1308,13 +1311,14 @@ class AuthValidateResponse(TypedDict, total=False):# ── Template ──────────────────────────────────────────────────────-class TemplateRecord(TypedDict, total=False):+class TemplateRecord(TypedDict):id: strsessionId: strname: str- body: str # template body with {{variable}} placeholders- header: str | None- footer: str | None+ # template body with {{variable}} placeholders+ body: str+ header: NotRequired[str | None]+ footer: NotRequired[str | None]createdAt: strupdatedAt: str@@ -1339,7 +1343,7 @@ class UpdateTemplateRequest(TypedDict, total=False):# Mirrors the backend ``Label`` — returned by the engine as-is, with no DTO in between.# ``hexColor`` is the only colour field the wire shape carries, e.g. ``#25D366``.-class LabelRecord(TypedDict, total=False):+class LabelRecord(TypedDict):id: strname: strhexColor: str@@ -1355,26 +1359,26 @@ class AddLabelRequest(TypedDict):# Mirrors the backend ``Channel`` — returned by the engine as-is, with no DTO in between.# ``createdAt`` is populated by Baileys; whatsapp-web.js omits it. ``picture`` is not currently# filled by either engine.-class ChannelRecord(TypedDict, total=False):+class ChannelRecord(TypedDict):id: Jidname: str- description: str- inviteCode: str- subscriberCount: int- picture: str- verified: bool- createdAt: int+ description: NotRequired[str]+ inviteCode: NotRequired[str]+ subscriberCount: NotRequired[int]+ picture: NotRequired[str]+ verified: NotRequired[bool]+ createdAt: NotRequired[int]# A message read live from a channel by ``channels.messages()`` — the engine payload# (backend ``ChannelMessage``), NOT the persisted MessageRecord. ``timestamp`` is a Unix# timestamp in seconds.-class ChannelMessageRecord(TypedDict, total=False):+class ChannelMessageRecord(TypedDict):id: strbody: strtimestamp: inthasMedia: bool- mediaUrl: str+ mediaUrl: NotRequired[str]class ChannelMessageQuery(TypedDict, total=False):@@ -1390,10 +1394,10 @@ class SubscribeChannelRequest(TypedDict):# ── Catalog (Business) ────────────────────────────────────────────-class CatalogInfo(TypedDict, total=False):+class CatalogInfo(TypedDict):id: strname: str- description: str | None+ description: NotRequired[str]# Counts at most the first 51 products on Baileys.productCount: inturl: str@@ -1404,17 +1408,17 @@ class CatalogProductsQuery(TypedDict, total=False):limit: int-class CatalogProduct(TypedDict, total=False):+class CatalogProduct(TypedDict):id: strname: str- description: str | None- price: float- currency: str- priceFormatted: str- imageUrl: str | None+ description: NotRequired[str]+ price: NotRequired[float]+ currency: NotRequired[str]+ priceFormatted: NotRequired[str]+ imageUrl: NotRequired[str]url: strisAvailable: bool- retailerId: str+ retailerId: NotRequired[str]class ProductPagination(TypedDict):@@ -1521,7 +1525,7 @@ class SearchResults(TypedDict):provider: str-class ConvertedMedia(TypedDict, total=False):+class ConvertedMedia(TypedDict):"""Converted media, shaped for handing straight to a send call."""#: The converted bytes, ready to use as a send call's ``base64``.@@ -1532,7 +1536,7 @@ class ConvertedMedia(TypedDict, total=False):bytes: int-class MediaConversionAvailability(TypedDict, total=False):+class MediaConversionAvailability(TypedDict):"""Whether server-side conversion can be used on this deployment."""available: bool