Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

fix(sdk): compare a nullable enum or array in the shape gate

Yudhi Armyndharis73c7de91dd8d
diff --git a/scripts/check-contract-shapes.mjs b/scripts/check-contract-shapes.mjs
index 0bdf4aa92..c165e42c8 100644
--- a/scripts/check-contract-shapes.mjs
+++ b/scripts/check-contract-shapes.mjs
@@ -803,6 +803,9 @@ export function handToken(text, types, depth = 0) {
const nullable = parts.includes('null');
const rest = parts.filter(p => p !== 'null');
if (nullable && rest.length === 1) return `${handToken(rest[0], types, depth)}|null`;
+ // A nullable literal union ('a' | 'b' | null) is the enum of its literals with a null arm.
+ const inner = nullable && rest.length > 1 ? handToken(rest.join(' | '), types, depth) : '';
+ if (inner.startsWith('enum(')) return `${inner}|null`;
return `union(${rest
.map(p => handToken(p, types, depth))
.sort()
@@ -831,7 +834,11 @@ function baseSchemaToken(node, schemas, depth = 0) {
const target = schemas[node.$ref.split('/').pop()];
return depth < MAX_DEPTH ? schemaToken(target, schemas, depth + 1) : 'object';
}
- if (node.enum) return `enum(${sortEnumMembers(node.enum.map(String)).join(',')})`;
+ if (node.enum) {
+ // OpenAPI 3.0 lists null among the members of a nullable enum; schemaToken adds the null arm back.
+ const members = node.nullable === true ? node.enum.filter(m => m !== null) : node.enum;
+ return `enum(${sortEnumMembers(members.map(String)).join(',')})`;
+ }
if (node.type === 'array') return `array<${schemaToken(node.items, schemas, depth)}>`;
if (node.anyOf || node.oneOf) {
const parts = (node.anyOf ?? node.oneOf).map(n => schemaToken(n, schemas, depth + 1));
@@ -890,9 +897,10 @@ export function parseObjectToken(token) {
/** Fields whose both sides reduce to a primitive/enum/array/null-union get token-level diffing.
* `array<enum(...)>` counts: an array of enum members is exactly as comparable as a bare one, and
* leaving it out silently ungated every vocabulary that travels as a list, the webhook event set
- * above all, on every client at once. */
+ * above all, on every client at once. So does a null arm after an enum or an array: a nullable
+ * field was skipped, and with it the vocabulary of SessionProxy.proxyType. */
function isSimpleToken(token) {
- return /^(string|number|boolean|unknown|any)(\|null)?$|^enum\([^)]*\)$|^array<((string|number|boolean)(\|null)?|enum\([^)]*\))>$/.test(
+ return /^(string|number|boolean|unknown|any)(\|null)?$|^enum\([^)]*\)(\|null)?$|^array<((string|number|boolean)(\|null)?|enum\([^)]*\))>(\|null)?$/.test(
token,
);
}
@@ -1100,13 +1108,16 @@ function pythonToken(text, resolve, depth = 0) {
if (t.endsWith(',')) t = t.slice(0, -1).trim();
if (depth >= 4) return 'object';
let nullable = false;
- if (/\|\s*None$/.test(t) || /^Optional\[/.test(t)) {
+ if (/^Optional\[/.test(t)) {
nullable = true;
t = t
.replace(/^Optional\[/, '')
- .replace(/\s*\|\s*None$/, '')
.replace(/\]$/, '')
.trim();
+ } else if (/\|\s*None$/.test(t)) {
+ // No bracket to strip here: the last one belongs to the type (`Literal["x"] | None`, `list[str] | None`).
+ nullable = true;
+ t = t.replace(/\s*\|\s*None$/, '').trim();
}
const base = (() => {
if (t === 'str') return 'string';
diff --git a/scripts/check-contract-shapes.spec.mjs b/scripts/check-contract-shapes.spec.mjs
index 34735f4b6..6f6541105 100644
--- a/scripts/check-contract-shapes.spec.mjs
+++ b/scripts/check-contract-shapes.spec.mjs
@@ -315,6 +315,57 @@ test('isSimpleToken-gated diffing reaches inside an array of enum members', () =
assert.match(diffs[0], /events/);
});
+test('a nullable enum is compared on both sides, the null member of the contract enum set aside', () => {
+ // OpenAPI 3.0 lists null among the members of a nullable enum; the vocabulary is the other members.
+ // The token used to end in `|null`, which no comparison accepted, so such a field was never compared.
+ const kind = { type: 'string', nullable: true, enum: ['a', 'b', null] };
+ const schema = { type: 'object', required: ['kind'], properties: { kind } };
+ assert.equal(schemaToken(kind, {}), 'enum(a,b)|null');
+ assert.equal(handToken("'b' | 'a' | null", {}), 'enum(a,b)|null');
+
+ const hand = { kind: { optional: false, token: "'a' | 'b' | null" } };
+ assert.deepEqual(comparePair('Hand', hand, 'Dto', schema, {}), []);
+ // A member the contract gained, and a null arm the hand lacks, are drift.
+ const gained = { ...schema, properties: { kind: { ...kind, enum: ['a', 'b', 'c', null] } } };
+ assert.deepEqual(comparePair('Hand', hand, 'Dto', gained, {}), [
+ '"kind": hand enum(a,b)|null, contract enum(a,b,c)|null',
+ ]);
+ const notNull = { kind: { optional: false, token: "'a' | 'b'" } };
+ assert.deepEqual(comparePair('Hand', notNull, 'Dto', schema, {}), [
+ '"kind": hand enum(a,b), contract enum(a,b)|null',
+ ]);
+});
+
+test('a nullable array is compared on both sides', () => {
+ const ids = { type: 'array', items: { type: 'string' }, nullable: true };
+ const schema = { type: 'object', required: ['ids'], properties: { ids } };
+ assert.deepEqual(comparePair('Hand', { ids: { optional: false, token: 'string[] | null' } }, 'Dto', schema, {}), []);
+ assert.deepEqual(comparePair('Hand', { ids: { optional: false, token: 'string[]' } }, 'Dto', schema, {}), [
+ '"ids": hand array<string>, contract array<string>|null',
+ ]);
+});
+
+test('parsePythonTypes: a nullable Literal or list keeps its closing bracket and gains a null arm', () => {
+ const src = [
+ 'class Sample(TypedDict):',
+ ' a: Literal["x", "y"] | None',
+ ' b: Optional[Literal["x", "y"]]',
+ ' c: list[str] | None',
+ ' d: Optional[List[str]]',
+ ' e: str | None',
+ ].join('\n');
+ // The `| None` form lost its last bracket to the strip meant for Optional[...], so `Literal["x", "y"] | None`
+ // read as the unparseable `Literal["x", "y"` and the field was never compared.
+ const tokens = Object.values(parsePythonTypes(src).Sample).map(v => v.token);
+ assert.deepEqual(tokens, [
+ 'enum(x,y)|null',
+ 'enum(x,y)|null',
+ 'array<string>|null',
+ 'array<string>|null',
+ 'string|null',
+ ]);
+});
+
test('parseJavaTypes: a package-qualified generic is the same shape as the bare one', () => {
// Two request records spell the mentions list `java.util.List<String>`; matching only `List<...>`
// left it resolving to its raw text, so its type went uncompared while the field still counted