docs(openapi): declare POST /v1/customer/bulk 201 envelope shape (#332)

app/config/openapi.js

@@ -572,6 +572,27 @@ const spec = {
                         // see it on all 13 bulk endpoints, not 12-of-13.
                         // Matches the factory output from #168.
                         headers: idempotencyReplayResponseHeader,
+                        // Controller (`_bulk-helpers.makeBulkCreate`) emits
+                        // `{message, count, customers}` on success. The spec
+                        // previously left the body unspecified — same drift
+                        // pattern fixed for single-create POST endpoints in
+                        // #316 (customer) and #326 (timeentry). Pin the
+                        // envelope here so SDK code-gen models the response.
+                        content: {
+                            'application/json': {
+                                schema: {
+                                    type: 'object',
+                                    properties: {
+                                        message: { type: 'string' },
+                                        count: { type: 'integer' },
+                                        customers: {
+                                            type: 'array',
+                                            items: { $ref: '#/components/schemas/Customer' },
+                                        },
+                                    },
+                                },
+                            },
+                        },
                     },
                     400: { description: 'Validation failure (array empty / master without custCompId on some entry)' },
                     403: { description: 'Missing authKey or cross-tenant create attempt' },

tests/api/openapi.test.js

@@ -70,6 +70,22 @@ describe('OpenAPI spec', () => {
         expect(schemas.TimeEntry.properties.teStartedAt).toBeDefined();
     });
 
+    test('POST /v1/customer/bulk 201 declares the {message, count, customers} envelope', async () => {
+        // makeBulkCreate (app/controllers/_bulk-helpers.js) emits
+        // {message, count, <createdKey>}. The spec previously had
+        // description + headers but no content schema, so SDK
+        // code-gen modeled the response as untyped. Same drift
+        // pattern as #316 / #326 but for the bulk variant.
+        const res = await request(app).get('/openapi.json');
+        const r201 = res.body.paths['/v1/customer/bulk'].post.responses['201'];
+        const schema = r201.content['application/json'].schema;
+        expect(schema.type).toBe('object');
+        expect(schema.properties.message).toBeDefined();
+        expect(schema.properties.count.type).toBe('integer');
+        expect(schema.properties.customers.type).toBe('array');
+        expect(schema.properties.customers.items.$ref).toBe('#/components/schemas/Customer');
+    });
+
     test('POST /v1/timeentry 201 declares the {message, timeEntry} envelope', async () => {
         // Same envelope-drift fix as #316 (customer POST) and #312
         // (customer GET). Pre-fix the timeentry POST 201 had no