feat(client): pass overwrite through packages.install for upgrade flows (#3007)

POST /packages now 409s when the manifest id is already installed (#2971,
duplicate-id guard). The SDK's packages.install() had no way to opt into the
intentional-overwrite escape hatch, so any upgrade / re-install flow built on
it would hit the 409 with no recourse.

Add `overwrite?: boolean` to the options bag and pass it through the POST body
only when explicitly set — the default request stays byte-identical so the
server keeps rejecting duplicate ids. First SDK tests for packages.install
(default omits the flag; overwrite:true carries it).

Co-authored-by: Jack Zhuang <277994282+os-zhuang@users.noreply.github.com>
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>

Author: os-zhuang

packages/client/src/client.test.ts

@@ -1179,3 +1179,28 @@ describe('HTTP error shaping', () => {
         expect(caught.httpStatus).toBe(500);
     });
 });
+
+describe('packages.install', () => {
+    const MANIFEST = { id: 'com.acme.crm', name: 'Acme CRM', version: '1.0.0', type: 'app' };
+
+    it('POSTs the manifest and omits `overwrite` unless requested', async () => {
+        const { client, fetchMock } = createMockClient({ success: true, data: { package: { manifest: MANIFEST } } });
+        await client.packages.install(MANIFEST, { enableOnInstall: true });
+
+        expect(fetchMock).toHaveBeenCalledWith('http://localhost:3000/api/v1/packages', expect.any(Object));
+        const body = JSON.parse(fetchMock.mock.calls[0][1].body);
+        expect(body.manifest).toEqual(MANIFEST);
+        expect(body.enableOnInstall).toBe(true);
+        // Duplicate-id guard semantics: never send `overwrite` implicitly —
+        // the server must keep 409ing on an existing id by default.
+        expect('overwrite' in body).toBe(false);
+    });
+
+    it('passes `overwrite: true` through for intentional upgrade / re-install', async () => {
+        const { client, fetchMock } = createMockClient({ success: true, data: { package: { manifest: MANIFEST } } });
+        await client.packages.install(MANIFEST, { overwrite: true });
+
+        const body = JSON.parse(fetchMock.mock.calls[0][1].body);
+        expect(body.overwrite).toBe(true);
+    });
+});

packages/client/src/index.ts

@@ -592,15 +592,24 @@ export class ObjectStackClient {
 
     /**
      * Install a new package from its manifest.
-     */
-    install: async (manifest: any, options?: { settings?: Record<string, any>; enableOnInstall?: boolean }) => {
+     *
+     * By default the server rejects a manifest whose `id` is already
+     * installed with **409 Conflict** (duplicate-id guard) instead of
+     * silently overwriting the existing package. Intentional upgrade /
+     * re-install flows opt back in with `overwrite: true`.
+     */
+    install: async (
+        manifest: any,
+        options?: { settings?: Record<string, any>; enableOnInstall?: boolean; overwrite?: boolean },
+    ) => {
         const route = this.getRoute('packages');
         const res = await this.fetch(`${this.baseUrl}${route}`, {
             method: 'POST',
             body: JSON.stringify({
                 manifest,
                 settings: options?.settings,
                 enableOnInstall: options?.enableOnInstall,
+                ...(options?.overwrite !== undefined ? { overwrite: options.overwrite } : {}),
             }),
         });
         return this.unwrapResponse<{ package: any; message?: string }>(res);