@mondaydotcomorg/z2h-cli 0.34.0 → 0.34.2

package/src/commands/__tests__/deploy.test.ts

@@ -18,6 +18,9 @@ import * as brokerApp from '../../util/broker/app';
 import * as authStore from '../../util/auth/auth-store';
 import * as gitRepo from '../../util/git/repo';
 import { updateOrCreateUsageJson } from '../../util/usage-json';
+import { putAppUsage } from '../../util/usage-upload';
+
+vi.mock('../../util/usage-upload', () => ({ putAppUsage: vi.fn() }));
 
 vi.mock('../build', () => ({
   buildCommand: vi.fn(),
@@ -26,7 +29,7 @@ vi.mock('../build', () => ({
 // Wraps the real `deployBackend` so most tests exercise it unchanged (no
 // backend/handlers dir in the tmp fixture, so it resolves trivially), while
 // letting individual tests override it to prove the upload/register ordering
-// and passthrough of real handlerNames/apiUsages.
+// and passthrough of real handlerNames.
 vi.mock('../backend', async importOriginal => {
   const actual = await importOriginal<typeof import('../backend')>();
   return { ...actual, deployBackend: vi.fn(actual.deployBackend) };
@@ -119,7 +122,7 @@ describe('deploy --preview', () => {
     vi.mocked(setupS3Client).mockClear();
     vi.mocked(openInBrowser).mockClear();
     vi.mocked(brokerProvider.brokerCredentialProvider).mockClear();
-    vi.mocked(brokerProvider.fetchDeployVersion).mockReset().mockResolvedValue(0);
+    vi.mocked(brokerProvider.fetchDeployVersion).mockReset().mockResolvedValue({ version: 0, id: 7 });
     vi.mocked(brokerApp.registerOrUpdateApp).mockClear().mockResolvedValue(undefined);
     vi.mocked(brokerApp.fetchApp).mockClear().mockResolvedValue(STUB_MASTER_APP);
     vi.mocked(gitRepo.guardCleanTree).mockClear();
@@ -163,7 +166,7 @@ describe('deploy --preview', () => {
 
   it('reuses the sticky previewId from metadata', async () => {
     await writeMetadata(STUB_PREVIEW_ID);
-    vi.mocked(brokerProvider.fetchDeployVersion).mockResolvedValue(2);
+    vi.mocked(brokerProvider.fetchDeployVersion).mockResolvedValue({ version: 2, id: 7 });
 
     await deployCommand({ preview: true });
 
@@ -181,14 +184,13 @@ describe('deploy --preview', () => {
       gitRemote: '',
       integrations: [],
       handlerNames: [],
-      apiUsages: {},
       masterAppName: 'mf-my-app',
     });
   });
 
   it('calls registerOrUpdateApp for a brand-new preview at version 1 with an empty gitRemote', async () => {
     await writeMetadata(STUB_PREVIEW_ID);
-    vi.mocked(brokerProvider.fetchDeployVersion).mockResolvedValue(0);
+    vi.mocked(brokerProvider.fetchDeployVersion).mockResolvedValue({ version: 0, id: 7 });
 
     await deployCommand({ preview: true });
 
@@ -201,7 +203,6 @@ describe('deploy --preview', () => {
       gitRemote: '',
       integrations: [],
       handlerNames: [],
-      apiUsages: {},
       masterAppName: 'mf-my-app',
     });
   });
@@ -225,6 +226,7 @@ describe('deploy --preview', () => {
     expect(gitRepo.pullAndResolve).not.toHaveBeenCalled();
     expect(gitRepo.pushToRemote).not.toHaveBeenCalled();
     expect(updateOrCreateUsageJson).not.toHaveBeenCalled();
+    expect(putAppUsage).not.toHaveBeenCalled();
     expect(gitRepo.initRepo).not.toHaveBeenCalled();
   });
 
@@ -317,11 +319,10 @@ describe('deploy --preview', () => {
     warnSpy.mockRestore();
   });
 
-  it('forwards the real handlerNames and apiUsages deployBackend reports to registerOrUpdateApp', async () => {
+  it('forwards the real handlerNames deployBackend reports to registerOrUpdateApp', async () => {
     vi.mocked(backendCmd.deployBackend).mockResolvedValueOnce({
       integrations: ['snowflake'],
       handlerNames: ['call_snowflake'],
-      apiUsages: { call_snowflake: { snowflake: { query: [{ sql: 'x' }] } } },
     });
 
     await deployCommand({ preview: true });
@@ -330,7 +331,6 @@ describe('deploy --preview', () => {
       expect.objectContaining({
         integrations: ['snowflake'],
         handlerNames: ['call_snowflake'],
-        apiUsages: { call_snowflake: { snowflake: { query: [{ sql: 'x' }] } } },
       })
     );
   });
@@ -349,7 +349,7 @@ describe('deploy failure reasons', () => {
     await ensureDir(path.join(tmp, '.zth', 'build'));
 
     vi.spyOn(authStore, 'readZthAuth').mockResolvedValue({ token: 'jwt-stub' });
-    vi.mocked(brokerProvider.fetchDeployVersion).mockReset().mockResolvedValue(0);
+    vi.mocked(brokerProvider.fetchDeployVersion).mockReset().mockResolvedValue({ version: 0, id: 7 });
     vi.mocked(gitRepo.getRemoteUrl).mockReset().mockResolvedValue('https://github.com/org/repo.git');
     vi.mocked(gitRepo.guardCleanTree).mockReset().mockResolvedValue(undefined);
     vi.mocked(gitRepo.pullAndResolve).mockReset().mockResolvedValue(undefined);
@@ -414,7 +414,7 @@ describe('deploy failure reasons', () => {
 
   it('updates usage.json before pushing on a live deploy', async () => {
     vi.stubGlobal('fetch', vi.fn().mockResolvedValue({ ok: true, status: 200, text: async () => '' }));
-    vi.mocked(updateOrCreateUsageJson).mockReset().mockResolvedValue(undefined);
+    vi.mocked(updateOrCreateUsageJson).mockReset().mockResolvedValue({});
     vi.mocked(gitRepo.pushToRemote).mockReset().mockRejectedValue(new Error('stop after push'));
     await deployCommand().catch(() => {});
     const [usageOrder] = vi.mocked(updateOrCreateUsageJson).mock.invocationCallOrder;
@@ -422,6 +422,38 @@ describe('deploy failure reasons', () => {
     expect(usageOrder).toBeLessThan(pushOrder);
   });
 
+  describe('usage upload', () => {
+    beforeEach(() => {
+      vi.stubGlobal('fetch', vi.fn().mockResolvedValue({ ok: true, status: 200, text: async () => '' }));
+      vi.mocked(brokerProvider.fetchDeployVersion).mockResolvedValue({ version: 4, id: 7 });
+      vi.mocked(updateOrCreateUsageJson).mockReset().mockResolvedValue({ deployedBy: 'me' });
+      vi.mocked(gitRepo.pushToRemote).mockReset().mockResolvedValue(undefined);
+      vi.mocked(putAppUsage).mockClear();
+    });
+
+    it('uploads under the new deploy version after the release is registered', async () => {
+      vi.mocked(brokerApp.registerOrUpdateApp).mockClear();
+      await deployCommand();
+      expect(putAppUsage).toHaveBeenCalledWith('mf-my-app', 7, { deployedBy: 'me' }, 5);
+      expect(vi.mocked(brokerApp.registerOrUpdateApp).mock.invocationCallOrder[0]).toBeLessThan(
+        vi.mocked(putAppUsage).mock.invocationCallOrder[0]
+      );
+    });
+
+    it('uploads nothing when registration fails', async () => {
+      vi.mocked(brokerApp.registerOrUpdateApp).mockRejectedValueOnce(new Error('broker down'));
+      await deployCommand().catch(() => {});
+      expect(putAppUsage).not.toHaveBeenCalled();
+    });
+
+    it('uploads nothing on a dry run or when the build fails', async () => {
+      await deployCommand({ dryRun: true });
+      vi.mocked(buildCommand).mockRejectedValueOnce(new Error('tsc exploded'));
+      await deployCommand().catch(() => {});
+      expect(putAppUsage).not.toHaveBeenCalled();
+    });
+  });
+
   // buildCommand throws plain errors (see commands/__tests__/build.test.ts), so a build
   // failure surfaces as untagged here — see the propagation test below. The STS 401/403 →
   // auth tagging lives in broker-credential-provider.ts — see its own test file.

package/src/commands/backend.ts

@@ -26,7 +26,6 @@ function currentAppName(): string {
 export interface ReadDetectAndUploadResult {
   integrations: string[];
   handlerNames: string[];
-  apiUsages: Record<string, unknown>;
 }
 
 async function readDetectAndUpload(
@@ -38,14 +37,14 @@ async function readDetectAndUpload(
   logLabel: string
 ): Promise<ReadDetectAndUploadResult> {
   if (!hasHandlers(appDir)) {
-    return { integrations: [], handlerNames: [], apiUsages: {} };
+    return { integrations: [], handlerNames: [] };
   }
   info(`reading backend handlers ${logLabel}`);
-  const { handlers, apiDomains, apiUsages } = await readHandlers(appDir);
+  const { handlers, apiDomains } = await readHandlers(appDir);
   const integrations = detectIntegrations(apiDomains);
   const handlerNames = Object.keys(handlers);
   if (Object.keys(handlers).length === 0) {
-    return { integrations, handlerNames, apiUsages };
+    return { integrations, handlerNames };
   }
   const s3 = getS3Client();
   const meta = JSON.stringify({ version, deployedBy, handlers: Object.keys(handlers) });
@@ -55,7 +54,7 @@ async function readDetectAndUpload(
     ...Object.entries(handlers).map(([name, code]) => put(`${prefix}/${name}.js`, code, 'application/javascript')),
     put(`${prefix}/meta.json`, meta, 'application/json'),
   ]);
-  return { integrations, handlerNames, apiUsages };
+  return { integrations, handlerNames };
 }
 
 /**

package/src/commands/deploy.ts

@@ -16,6 +16,7 @@ import { readZthAuth } from '../util/auth/auth-store';
 import { cleanAppName, mfAppName, validateAppName, buildPreviewSlug } from '../util/app-name';
 import { getRemoteUrl, guardCleanTree, pullAndResolve, pushToRemote, initRepo } from '../util/git/repo';
 import { updateOrCreateUsageJson } from '../util/usage-json';
+import { putAppUsage } from '../util/usage-upload';
 import { resolveGitEnv } from '../util/git/git-env';
 import { type RemoteType, validateRemoteOptions, resolveRemoteUrl } from '../util/git/remote-options';
 import { setupS3Client } from '../util/s3/client';
@@ -134,7 +135,7 @@ async function uploadAndRegister(opts: {
 
   // Runs before the frontend upload so a `deployBackend` failure can't leave a
   // preview's unversioned `MF` dir overwritten with no rollback.
-  const { integrations, handlerNames, apiUsages } = await deployBackend({
+  const { integrations, handlerNames } = await deployBackend({
     appDir: process.cwd(),
     appName,
     mfKeyPrefix: keyPrefix,
@@ -155,7 +156,6 @@ async function uploadAndRegister(opts: {
       gitRemote,
       integrations,
       handlerNames,
-      apiUsages,
       description,
       masterAppName,
     });
@@ -197,7 +197,7 @@ async function deployPreview({ paths, consumerName, appName, token, opts }: Depl
 
   // No catch-all: every stage below tags its own DeployError reason at the throw site,
   // and anything unclassified reports as `unknown` via reasonOf() in runCommand.
-  const nextVersion = (await fetchDeployVersion(previewAppName)) + 1;
+  const nextVersion = (await fetchDeployVersion(previewAppName)).version + 1;
 
   info('building');
   const entry = await buildAndStamp({
@@ -276,11 +276,13 @@ async function deployLive({ paths, consumerName, appName, token, opts }: DeployC
     gitRemote = remote;
   }
 
-  const version = await fetchDeployVersion(appName);
+  const { version, id: appId } = await fetchDeployVersion(appName);
   const nextVersion = version + 1;
 
   const gitEnv = await resolveGitEnv(appName, gitRemote);
 
+  let usage: Record<string, unknown> = {};
+
   // Sync git first so a divergence (GitConflictError) stops us.
   // The skill commits the working tree (with an LLM-authored message) before
   // invoking deploy, so the tree should be clean here.
@@ -289,7 +291,7 @@ async function deployLive({ paths, consumerName, appName, token, opts }: DeployC
       await guardCleanTree(process.cwd());
       info('syncing with git remote');
       await pullAndResolve(process.cwd(), gitEnv);
-      await updateOrCreateUsageJson(process.cwd(), appName, whoAmI());
+      usage = await updateOrCreateUsageJson(process.cwd(), appName, whoAmI());
     } catch (err) {
       throw tagDeployError('git_error', err);
     }
@@ -351,6 +353,8 @@ async function deployLive({ paths, consumerName, appName, token, opts }: DeployC
     await releaseLockBestEffort(appName, token);
   }
 
+  await putAppUsage(appName, appId, usage, nextVersion);
+
   // Tags are a post-deploy concern: the S3 upload has already succeeded, so a
   // tag failure never fails the deploy (handled inside).
   await handleDeployTags(appName);

package/src/constants.ts

@@ -28,53 +28,27 @@ export const MAX_PORT = 19999;
 // ─────────── Gitignore entries auto-appended to the consumer's file ────
 export const GITIGNORE_ENTRIES = ['.zth/'];
 
-// ─────────── Z2H deploy bucket / contract ─────────
-// Source of truth for the bucket layout. The CLI uses these when configuring
-// the S3 client + uploading; bigbrain-zth's STS broker imports them via
-// `@mondaydotcomorg/z2h-cli/constants` to scope the per-deploy session
-// policy to the same bucket + manifest key.
-
-export const BUCKET_WRITE_NAME = 'prod-use1-bigbrain-zth-mf-assets';
-export const REGION = 'us-east-1';
-export const BUCKET_WRITE_URL = `https://${BUCKET_WRITE_NAME}.s3.${REGION}.amazonaws.com`;
-
-export const BUCKET_READ_DNS_NAME = 'bigbrain-zth-mf-assets';
-export const BUCKET_READ_DNS_URL = `https://${BUCKET_READ_DNS_NAME}.bigbrain.me`;
-
-// Root prefix for ephemeral preview uploads: `previews/<previewAppName>/MF/...`,
-// where previewAppName is the preview's own `mf-zth-preview-<id>-<app>` name.
-// Shared by the CLI (upload path) and bigbrain-zth (STS policy + manifest overlay).
-export const S3_PREVIEWS_FOLDER = 'previews';
-
-// No `.json` extension — TridentSkeleton's `mfUrl` API appends `/mf-assets`
-// to the bucket base when fetching, so the manifest must live at this exact
-// key. See microfrontends/mf-bigbrain-zth/.../ZeroToHeroHost.tsx.
-export const MANIFEST_KEY = 'mf-assets';
-export const MANIFEST_READ_URL = `${BUCKET_READ_DNS_URL}/${MANIFEST_KEY}`;
-
-// ─────────── Skills bucket (read-only) ─────────
-// bigbrain-zth mints read-only STS creds scoped to this bucket (mintDatavizSkillsCredentials);
-// bigbrain-zth-agent syncs from it into its vendor/ at pod startup (syncDatavizVendor).
-// Both import from here so the two sides can't drift.
-export const S3_SKILLS_BUCKET_NAME = 'prod-use1-bigbrain-zth-skills';
-
-// Prefix the dataviz design-system skills are published under
-// (by data-cookbook's own CI on merge to master).
-export const DATAVIZ_SKILLS_PREFIX = 'dataviz/';
-
-// ─────────── App-name slug — backend & CLI both honor this ─────
-// Lowercase kebab-case, must start with a letter, 2-50 chars total. The
-// backend STS broker rejects anything else with 400; the CLI can validate
-// upfront for friendlier errors.
-export const APP_NAME_PATTERN = /^[a-z][a-z0-9-]{1,49}$/;
-
-export const PREVIEW_APP_NAME_PREFIX = 'zth-preview-';
-
-// ─────────── Backend channels — re-exported from shared-utils ─────
-// Single source of truth lives in `@mondaydotcomorg/z2h-shared-utils` so the
-// CLI detector and broker stay in lockstep. Kept here for existing
-// `@mondaydotcomorg/z2h-cli/constants` consumers.
-export { ALWAYS_ON_CHANNELS, DECLARED_INTEGRATIONS, type DeclaredIntegration } from '@mondaydotcomorg/z2h-shared-utils';
+// ─────────── Re-exported from shared-utils (source of truth) ─────
+// Kept here so existing CLI imports of ./constants keep working.
+export {
+  ALWAYS_ON_CHANNELS,
+  APP_USAGE_BUCKET_NAME,
+  appUsageFolder,
+  APP_NAME_PATTERN,
+  BUCKET_READ_DNS_NAME,
+  BUCKET_READ_DNS_URL,
+  BUCKET_WRITE_NAME,
+  BUCKET_WRITE_URL,
+  DATAVIZ_SKILLS_PREFIX,
+  DECLARED_INTEGRATIONS,
+  MANIFEST_KEY,
+  MANIFEST_READ_URL,
+  PREVIEW_APP_NAME_PREFIX,
+  REGION,
+  S3_PREVIEWS_FOLDER,
+  S3_SKILLS_BUCKET_NAME,
+  type DeclaredIntegration,
+} from '@mondaydotcomorg/z2h-shared-utils';
 
 // ─────────── Broker origin + npm registry (shared §3 contract) ─────
 // The bigbrain-zth broker fronts both the STS credential route and the npm
@@ -90,6 +64,10 @@ export function brokerBaseUrl(): string {
   return process.env.Z2H_BROKER_BASE_URL || DEFAULT_BROKER_BASE_URL;
 }
 
+export function isProdBroker(): boolean {
+  return brokerBaseUrl() === DEFAULT_BROKER_BASE_URL;
+}
+
 // Returns Baggage header for monday-mirror routing when Z2H_ROUTING_KEY is set.
 // No-op in production (returns {}) — only activates when the env var is set.
 export function routingHeaders(): Record<string, string> {

package/src/util/__tests__/usage-upload.test.ts

@@ -0,0 +1,58 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { warn } from '../logger';
+import { putAppUsage } from '../usage-upload';
+
+const { send } = vi.hoisted(() => ({ send: vi.fn() }));
+
+vi.mock('../logger', () => ({ warn: vi.fn() }));
+vi.mock('../s3/client', () => ({ getS3Client: () => ({ send }) }));
+
+describe('putAppUsage', () => {
+  const USAGE = { appName: 'stale', deployedBy: 'me', apiUsages: { a: 1 }, uploadVersion: 1 };
+
+  beforeEach(() => {
+    send.mockReset().mockResolvedValue({});
+  });
+
+  afterEach(() => {
+    vi.unstubAllEnvs();
+  });
+
+  it('uploads the usage under the given version', async () => {
+    await putAppUsage('mf-my-app', 7, USAGE, 4);
+
+    const { Bucket, Key, Body } = send.mock.calls[0][0].input;
+    expect(Bucket).toBe('de-integration-bigbrain');
+    expect(Key).toBe('prod/studio/entity=app_usage/mf-my-app_7/4/usage.json');
+    expect(JSON.parse(Body)).toEqual({
+      appName: 'mf-my-app',
+      appId: 7,
+      deployedBy: 'me',
+      apiUsages: { a: 1 },
+      uploadVersion: 4,
+    });
+  });
+
+  it('skips with a warning when targeting a non-prod broker', async () => {
+    vi.stubEnv('Z2H_BROKER_BASE_URL', 'https://staging.example.com');
+
+    await putAppUsage('mf-my-app', 7, USAGE, 4);
+
+    expect(send).not.toHaveBeenCalled();
+    expect(warn).toHaveBeenCalledWith(expect.stringContaining('https://staging.example.com'));
+  });
+
+  it('skips when the app row id is unknown', async () => {
+    await putAppUsage('mf-my-app', null, USAGE, 4);
+
+    expect(send).not.toHaveBeenCalled();
+  });
+
+  it('warns with the redeploy fix instead of throwing when the upload fails', async () => {
+    send.mockRejectedValue(new Error('denied'));
+
+    await expect(putAppUsage('mf-my-app', 7, USAGE, 4)).resolves.toBeUndefined();
+    expect(warn).toHaveBeenCalledWith(expect.stringContaining('z2h-cli deploy'));
+  });
+});

package/src/util/auth/__tests__/broker-credential-provider.test.ts

@@ -40,11 +40,11 @@ function mockFetchOnce(body: unknown, init: { status?: number; text?: string } =
 
 describe('fetchDeployVersion', () => {
   it('POSTs the appName to the version endpoint and returns the version', async () => {
-    const fetchMock = mockFetchOnce({ version: 4 });
+    const fetchMock = mockFetchOnce({ version: 4, id: 9 });
 
-    const version = await fetchDeployVersion('my-app');
+    const result = await fetchDeployVersion('my-app');
 
-    expect(version).toBe(4);
+    expect(result).toEqual({ version: 4, id: 9 });
     expect(fetchMock).toHaveBeenCalledWith(
       `${DEFAULT_BROKER_BASE_URL}${DEPLOY_VERSION_PATH}`,
       expect.objectContaining({
@@ -56,7 +56,7 @@ describe('fetchDeployVersion', () => {
 
   it('returns 0 when the broker returns no version field (new app)', async () => {
     mockFetchOnce({});
-    await expect(fetchDeployVersion('my-app')).resolves.toBe(0);
+    await expect(fetchDeployVersion('my-app')).resolves.toEqual({ version: 0, id: null });
   });
 
   it('surfaces a remediation hint on 401, tagged broker_auth', async () => {

package/src/util/auth/broker-credential-provider.ts

@@ -19,6 +19,7 @@ interface CredentialsResponse {
 
 interface VersionResponse {
   version?: number;
+  id?: number | null;
 }
 
 async function postToBroker(path: string, body: unknown): Promise<Response> {
@@ -67,12 +68,11 @@ async function assertBrokerOk(res: Response, errorLabel: string): Promise<void>
  * credentials call so version derivation lives on its own endpoint — the CLI
  * asks for the version first, then requests credentials scoped to it.
  */
-export async function fetchDeployVersion(appName: string): Promise<number> {
+export async function fetchDeployVersion(appName: string): Promise<Required<VersionResponse>> {
   const res = await postToBroker(DEPLOY_VERSION_PATH, { appName });
   await assertBrokerOk(res, 'deploy');
-  const body = (await res.json()) as VersionResponse;
-
-  return body.version ?? 0;
+  const { version = 0, id = null } = (await res.json()) as VersionResponse;
+  return { version, id };
 }
 
 async function requestSts(path: string, body: unknown, errorLabel: string): Promise<AwsCredentialIdentity> {

package/src/util/broker/app.ts

@@ -72,7 +72,6 @@ export interface RegisterOrUpdateOptions {
   gitRemote: string;
   integrations?: string[];
   handlerNames?: string[];
-  apiUsages?: Record<string, unknown>;
   description?: string;
   /**
    * The base app a preview is for, sent only on first registration — the link
@@ -91,7 +90,6 @@ async function registerApp(params: RegisterOrUpdateOptions & { visibility: 'publ
     gitRemote,
     integrations,
     handlerNames,
-    apiUsages,
     description,
     masterAppName,
   } = params;
@@ -106,7 +104,6 @@ async function registerApp(params: RegisterOrUpdateOptions & { visibility: 'publ
       gitRemote,
       integrations,
       handlerNames,
-      apiUsages,
       description,
       masterAppName,
     }),
@@ -119,21 +116,11 @@ async function registerApp(params: RegisterOrUpdateOptions & { visibility: 'publ
 
 /** Releases a new version onto an app that already exists. */
 async function updateApp(params: RegisterOrUpdateOptions): Promise<void> {
-  const {
-    appName,
-    token,
-    nextVersion: version,
-    entry,
-    gitRemote,
-    integrations,
-    handlerNames,
-    apiUsages,
-    description,
-  } = params;
+  const { appName, token, nextVersion: version, entry, gitRemote, integrations, handlerNames, description } = params;
   const res = await fetch(`${brokerBaseUrl()}/z2h-cli/apps/update`, {
     method: 'POST',
     headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json', ...routingHeaders() },
-    body: JSON.stringify({ appName, version, entry, gitRemote, integrations, handlerNames, apiUsages, description }),
+    body: JSON.stringify({ appName, version, entry, gitRemote, integrations, handlerNames, description }),
   });
   if (!res.ok) {
     const text = await res.text();

package/src/util/usage-json.ts

@@ -10,7 +10,7 @@ export function hasHandlers(appDir: string): boolean {
 }
 
 /** Other features may add top-level fields, so writes merge into the existing file instead of replacing it. */
-export async function writeUsageJson(appDir: string, patch: Record<string, unknown>): Promise<void> {
+export async function writeUsageJson(appDir: string, patch: Record<string, unknown>): Promise<Record<string, unknown>> {
   const file = path.join(appDir, 'usage.json');
   let existing: Record<string, unknown> = {};
   try {
@@ -20,16 +20,23 @@ export async function writeUsageJson(appDir: string, patch: Record<string, unkno
       throw err;
     }
   }
-  await writeJson(file, { ...existing, ...patch }, { spaces: 2 });
+  const merged = { ...existing, ...patch };
+  await writeJson(file, merged, { spaces: 2 });
+  return merged;
 }
 
 /** Refreshes the git-tracked `usage.json` and commits it if it changed, so a deploy's push carries it. */
-export async function updateOrCreateUsageJson(appDir: string, appName: string, deployedBy: string): Promise<void> {
+export async function updateOrCreateUsageJson(
+  appDir: string,
+  appName: string,
+  deployedBy: string
+): Promise<Record<string, unknown>> {
   const apiUsages = hasHandlers(appDir) ? (await readHandlers(appDir)).apiUsages : {};
-  await writeUsageJson(appDir, { appName, deployedBy, apiUsages });
+  const usage = await writeUsageJson(appDir, { appName, deployedBy, apiUsages });
   await execGit(['add', 'usage.json'], appDir);
   const { exitCode } = await execa('git', ['diff', '--cached', '--quiet'], { cwd: appDir, reject: false });
   if (exitCode !== 0) {
     await execGit(['commit', '-m', 'Update usage.json'], appDir);
   }
+  return usage;
 }

package/src/util/usage-upload.ts

@@ -0,0 +1,38 @@
+import { PutObjectCommand } from '@aws-sdk/client-s3';
+import { APP_USAGE_BUCKET_NAME, appUsageFolder, brokerBaseUrl, isProdBroker } from '../constants';
+import { warn } from './logger';
+import { getS3Client } from './s3/client';
+
+/** Snowpipe ignores re-uploads of an existing key, so the key is unique per app row id and deploy version. */
+export async function putAppUsage(
+  appName: string,
+  appId: number | null,
+  usage: Record<string, unknown>,
+  uploadVersion: number
+): Promise<void> {
+  if (!isProdBroker()) {
+    warn(
+      `skipping app usage upload to Snowflake: ${brokerBaseUrl()} is not the production broker, and only production deploys are recorded.`
+    );
+    return;
+  }
+  if (appId === null) {
+    return;
+  }
+  try {
+    await getS3Client().send(
+      new PutObjectCommand({
+        Bucket: APP_USAGE_BUCKET_NAME,
+        Key: `${appUsageFolder(appName, appId)}/${uploadVersion}/usage.json`,
+        Body: JSON.stringify({ ...usage, appName, appId, uploadVersion }),
+        ContentType: 'application/json',
+      })
+    );
+  } catch (err) {
+    warn(
+      `could not record app usage for Snowflake: ${
+        (err as Error).message
+      }. Your app is live. To record it, run \`z2h-cli deploy\` again (no changes or commit needed).`
+    );
+  }
+}