@superblocksteam/shared 0.9567.3 → 0.9568.0

package/dist-esm/utils/github-workflow.d.ts

@@ -0,0 +1,6 @@
+export declare const DEFAULT_SUPERBLOCKS_DOMAIN = "app.superblocks.com";
+export declare function isGitHubRemoteUrl(remoteUrl: string): boolean;
+export declare function buildGithubSuperblocksSyncWorkflow(domain?: string): string;
+export declare function getSuperblocksDomainFromBaseUrl(superblocksBaseUrl: string): string;
+export declare function buildGithubSuperblocksSyncWorkflowFromBaseUrl(superblocksBaseUrl: string): string;
+//# sourceMappingURL=github-workflow.d.ts.map

package/dist-esm/utils/github-workflow.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"github-workflow.d.ts","sourceRoot":"","sources":["../../src/utils/github-workflow.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,0BAA0B,wBAAwB,CAAC;AAEhE,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAE5D;AAED,wBAAgB,kCAAkC,CAAC,MAAM,GAAE,MAAmC,GAAG,MAAM,CA4CtG;AAED,wBAAgB,+BAA+B,CAAC,kBAAkB,EAAE,MAAM,GAAG,MAAM,CAWlF;AAED,wBAAgB,6CAA6C,CAAC,kBAAkB,EAAE,MAAM,GAAG,MAAM,CAEhG"}

package/dist-esm/utils/github-workflow.js

@@ -0,0 +1,65 @@
+export const DEFAULT_SUPERBLOCKS_DOMAIN = 'app.superblocks.com';
+export function isGitHubRemoteUrl(remoteUrl) {
+    return /(^git@github\.com:)|(^https?:\/\/github\.com\/)|(^ssh:\/\/git@github\.com\/)/.test(remoteUrl.trim());
+}
+export function buildGithubSuperblocksSyncWorkflow(domain = DEFAULT_SUPERBLOCKS_DOMAIN) {
+    return `name: Sync changes to Superblocks
+
+on:
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+
+jobs:
+  superblocks-sync:
+    runs-on: ubuntu-latest
+    name: Sync to Superblocks
+    permissions:
+      contents: read
+      packages: read
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+
+      # Optional: needed only if the CLI version is private in GitHub Packages.
+      - name: Setup npm credentials
+        env:
+          NPM_AUTH_TOKEN: \${{ secrets.NPM_AUTH_TOKEN }}
+        run: |
+          if [ -n "$NPM_AUTH_TOKEN" ]; then
+            echo "@superblocksteam:registry=https://npm.pkg.github.com" >> .npmrc
+            echo "always-auth=true" >> .npmrc
+            echo "//npm.pkg.github.com/:_authToken=$NPM_AUTH_TOKEN" >> .npmrc
+          fi
+
+      - name: Sync
+        uses: superblocksteam/sync-action@v1
+        env:
+          NPM_CONFIG_USERCONFIG: \${{ github.workspace }}/.npmrc
+        with:
+          token: \${{ secrets.SUPERBLOCKS_TOKEN }}
+          domain: ${domain}
+          path: .
+          sha: \${{ github.sha }}
+`;
+}
+export function getSuperblocksDomainFromBaseUrl(superblocksBaseUrl) {
+    const trimmed = superblocksBaseUrl.trim();
+    if (!trimmed) {
+        return DEFAULT_SUPERBLOCKS_DOMAIN;
+    }
+    try {
+        return new URL(trimmed).host || DEFAULT_SUPERBLOCKS_DOMAIN;
+    }
+    catch {
+        return DEFAULT_SUPERBLOCKS_DOMAIN;
+    }
+}
+export function buildGithubSuperblocksSyncWorkflowFromBaseUrl(superblocksBaseUrl) {
+    return buildGithubSuperblocksSyncWorkflow(getSuperblocksDomainFromBaseUrl(superblocksBaseUrl));
+}
+//# sourceMappingURL=github-workflow.js.map

package/dist-esm/utils/github-workflow.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"github-workflow.js","sourceRoot":"","sources":["../../src/utils/github-workflow.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,0BAA0B,GAAG,qBAAqB,CAAC;AAEhE,MAAM,UAAU,iBAAiB,CAAC,SAAiB;IACjD,OAAO,8EAA8E,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,CAAC,CAAC;AAC/G,CAAC;AAED,MAAM,UAAU,kCAAkC,CAAC,SAAiB,0BAA0B;IAC5F,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;oBAuCW,MAAM;;;CAGzB,CAAC;AACF,CAAC;AAED,MAAM,UAAU,+BAA+B,CAAC,kBAA0B;IACxE,MAAM,OAAO,GAAG,kBAAkB,CAAC,IAAI,EAAE,CAAC;IAC1C,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,OAAO,0BAA0B,CAAC;IACpC,CAAC;IAED,IAAI,CAAC;QACH,OAAO,IAAI,GAAG,CAAC,OAAO,CAAC,CAAC,IAAI,IAAI,0BAA0B,CAAC;IAC7D,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,0BAA0B,CAAC;IACpC,CAAC;AACH,CAAC;AAED,MAAM,UAAU,6CAA6C,CAAC,kBAA0B;IACtF,OAAO,kCAAkC,CAAC,+BAA+B,CAAC,kBAAkB,CAAC,CAAC,CAAC;AACjG,CAAC"}

package/dist-esm/utils/index.d.ts

@@ -1,4 +1,5 @@
 export * from './configuration.js';
+export * from './attachment-upload.js';
 export * from './env.js';
 export * from './environment.js';
 export * from './string.js';

package/dist-esm/utils/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AAAA,cAAc,oBAAoB,CAAC;AACnC,cAAc,UAAU,CAAC;AACzB,cAAc,kBAAkB,CAAC;AACjC,cAAc,aAAa,CAAC;AAC5B,cAAc,WAAW,CAAC;AAC1B,cAAc,eAAe,CAAC;AAC9B,cAAc,UAAU,CAAC;AACzB,cAAc,iBAAiB,CAAC;AAChC,cAAc,YAAY,CAAC;AAC3B,cAAc,WAAW,CAAC;AAC1B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,wBAAwB,CAAC;AAEvC,OAAO,MAAM,MAAM,2BAA2B,CAAC;AAC/C,OAAO,EAAE,MAAM,EAAE,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AAAA,cAAc,oBAAoB,CAAC;AACnC,cAAc,wBAAwB,CAAC;AACvC,cAAc,UAAU,CAAC;AACzB,cAAc,kBAAkB,CAAC;AACjC,cAAc,aAAa,CAAC;AAC5B,cAAc,WAAW,CAAC;AAC1B,cAAc,eAAe,CAAC;AAC9B,cAAc,UAAU,CAAC;AACzB,cAAc,iBAAiB,CAAC;AAChC,cAAc,YAAY,CAAC;AAC3B,cAAc,WAAW,CAAC;AAC1B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,wBAAwB,CAAC;AAEvC,OAAO,MAAM,MAAM,2BAA2B,CAAC;AAC/C,OAAO,EAAE,MAAM,EAAE,CAAC"}

package/dist-esm/utils/index.js

@@ -1,4 +1,5 @@
 export * from './configuration.js';
+export * from './attachment-upload.js';
 export * from './env.js';
 export * from './environment.js';
 export * from './string.js';

package/dist-esm/utils/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AAAA,cAAc,oBAAoB,CAAC;AACnC,cAAc,UAAU,CAAC;AACzB,cAAc,kBAAkB,CAAC;AACjC,cAAc,aAAa,CAAC;AAC5B,cAAc,WAAW,CAAC;AAC1B,cAAc,eAAe,CAAC;AAC9B,cAAc,UAAU,CAAC;AACzB,cAAc,iBAAiB,CAAC;AAChC,cAAc,YAAY,CAAC;AAC3B,cAAc,WAAW,CAAC;AAC1B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,wBAAwB,CAAC;AAEvC,OAAO,MAAM,MAAM,2BAA2B,CAAC;AAC/C,OAAO,EAAE,MAAM,EAAE,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AAAA,cAAc,oBAAoB,CAAC;AACnC,cAAc,wBAAwB,CAAC;AACvC,cAAc,UAAU,CAAC;AACzB,cAAc,kBAAkB,CAAC;AACjC,cAAc,aAAa,CAAC;AAC5B,cAAc,WAAW,CAAC;AAC1B,cAAc,eAAe,CAAC;AAC9B,cAAc,UAAU,CAAC;AACzB,cAAc,iBAAiB,CAAC;AAChC,cAAc,YAAY,CAAC;AAC3B,cAAc,WAAW,CAAC;AAC1B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,wBAAwB,CAAC;AAEvC,OAAO,MAAM,MAAM,2BAA2B,CAAC;AAC/C,OAAO,EAAE,MAAM,EAAE,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@superblocksteam/shared",
-  "version": "0.9567.3",
+  "version": "0.9568.0",
   "description": "Superblocks Shared Resources",
   "license": "Superblocks Community Software License",
   "repository": "https://github.com/superblocksteam/shared.git",

package/src/index.ts

@@ -8,6 +8,7 @@ export * from './observability/index.js';
 export * from './constants.js';
 export * from './pageMigrations/index.js';
 export * from './utils/appDSL.js';
+export * from './utils/github-workflow.js';
 export * from './pages/index.js';
 export * from './utils/page.js';
 export * from './utils/response-dto.js';

package/src/socket/protocol.ts

@@ -2,7 +2,17 @@
 
 import { DirectoryEntry, PutManyRequestPayload, PutManyResponsePayload } from '../dbfs/types.js';
 import { ApiToSign, ApiToVerify, AppToSign, AppToVerify, ApplicationSignatureTreeSigned, Signature } from '../signing/constants.js';
-import { AiChatMessageDto, AiChatMessagePayload, AiWorkflowEvent, FactListQuery, ListFactsResponse } from '../types/index.js';
+import {
+  AiChatMessageDto,
+  AiChatMessagePayload,
+  AiWorkflowEvent,
+  AiResolveAttachmentLeasesRequest,
+  AiResolveAttachmentLeasesResponse,
+  FactCreate,
+  FactDto,
+  FactListQuery,
+  ListFactsResponse
+} from '../types/index.js';
 import {
   ApplicationConfiguration,
   ApplicationPageClonePayload,
@@ -134,9 +144,15 @@ export interface ServerMethods {
           submit: ServerMethodSchema<AiWorkflowEvent, void>;
         };
       };
+      /**
+       * Resolve attachment leases and return fresh signed URLs.
+       * Called by ai-service to refresh attachment leases before sending to LLM.
+       */
+      resolveAttachmentLeases: ServerMethodSchema<AiResolveAttachmentLeasesRequest, AiResolveAttachmentLeasesResponse>;
     };
     fact: {
       list: ServerMethodSchema<FactListQuery, ListFactsResponse>;
+      create: ServerMethodSchema<FactCreate, FactDto>;
     };
   };
   v2: {
@@ -225,6 +241,10 @@ export interface ServerMethods {
     lock: {
       acquire: ServerMethodSchema<{ applicationId: string; branchName: string; sessionType: string }, GetAppBranchLockResponseBody>;
       release: ServerMethodSchema<{ applicationId: string; branchName: string; lockId: string }, void>;
+      transfer: ServerMethodSchema<
+        { applicationId: string; fromBranchName: string; toBranchName: string; lockId: string },
+        GetAppBranchLockResponseBody
+      >;
       grab: ServerMethodSchema<{ applicationId: string; branchName: string; lockId: string }, GetAppBranchLockResponseBody>;
       inspect: ServerMethodSchema<{ applicationId: string; branchName: string }, LockInfo>;
       forceTake: ServerMethodSchema<{ applicationId: string; branchName: string; sessionType: string }, GetAppBranchLockResponseBody>;

package/src/types/ai/index.ts

@@ -8,12 +8,59 @@ export type AiChatMessageDto = {
   authorName?: string | null;
 };
 
+/**
+ * Attachment reference for lease resolution.
+ */
+export interface AiAttachmentLeaseReference {
+  /** Stable URL of the attachment */
+  url: string;
+  /** Media/MIME type */
+  mediaType: string;
+  /** Original filename */
+  fileName: string;
+  /** Optional storage key in object storage */
+  storageKey?: string;
+  /** Scope of the attachment: org-wide or app-specific */
+  scopeType?: 'org' | 'app';
+  /** Application ID if scopeType is "app" */
+  applicationId?: string;
+}
+
+/**
+ * Resolved attachment with fresh signed URL.
+ */
+export interface AiResolvedAttachment {
+  url: string;
+  signedUrl: string;
+  expiresAt: string;
+  mimeType: string;
+}
+
+/**
+ * Request to resolve attachment leases via RPC.
+ */
+export interface AiResolveAttachmentLeasesRequest {
+  attachments: AiAttachmentLeaseReference[];
+  /** Scoped token for Bucketeer access (issued client-side). */
+  scopedToken: string;
+  /** Base URL of the Superblocks server, used to derive Bucketeer URL. */
+  superblocksBaseUrl: string;
+}
+
+/**
+ * Response with resolved attachment leases.
+ */
+export interface AiResolveAttachmentLeasesResponse {
+  attachments: AiResolvedAttachment[];
+}
+
 /**
  * System event trigger types for AI operations without prompt_id
  */
 export enum AiSystemTriggerType {
   APP_NAME = 'app_name',
   COMMIT_MESSAGE = 'commit_message',
+  DASHBOARD_CHAT = 'dashboard_chat',
   FACT_METADATA = 'fact_metadata'
 }
 
@@ -46,5 +93,4 @@ export interface AiWorkflowEvent {
   attributes: AiWorkflowAttributes;
 }
 
-export * from './credit-pricing.js';
 export * from './quota-paywall.js';

package/src/types/ai/quota-paywall.ts

@@ -1,8 +1,19 @@
-export type AiQuotaPaywallReason = 'token_limit_exceeded' | 'trial_expired';
+export type AiQuotaPaywallReason = 'credit_limit_exceeded' | 'no_seat_assigned' | 'token_limit_exceeded' | 'trial_expired';
 
 export const getAiQuotaPaywallReasonFromMessage = (message: string): AiQuotaPaywallReason | undefined => {
   const normalizedMessage = message.toLowerCase();
 
+  if (
+    normalizedMessage.includes('no_seat_assigned') ||
+    normalizedMessage.includes("doesn't have an ai builder license assigned") ||
+    normalizedMessage.includes("doesn't have an ai builder seat assigned") ||
+    normalizedMessage.includes('does not have an ai builder license assigned') ||
+    normalizedMessage.includes('does not have an ai builder seat assigned') ||
+    normalizedMessage.includes('no builder seat assigned')
+  ) {
+    return 'no_seat_assigned';
+  }
+
   if (
     normalizedMessage.includes('trial_expired') ||
     normalizedMessage.includes('ai trial period has ended') ||
@@ -11,7 +22,15 @@ export const getAiQuotaPaywallReasonFromMessage = (message: string): AiQuotaPayw
     return 'trial_expired';
   }
 
-  if (normalizedMessage.includes('token_limit_exceeded') || normalizedMessage.includes('ai usage limit')) {
+  if (normalizedMessage.includes('token_limit_exceeded')) {
+    return 'token_limit_exceeded';
+  }
+
+  if (normalizedMessage.includes('credit_limit_exceeded') || normalizedMessage.includes('organization has reached its ai usage limit')) {
+    return 'credit_limit_exceeded';
+  }
+
+  if (normalizedMessage.includes('ai usage limit')) {
     return 'token_limit_exceeded';
   }
 
@@ -22,11 +41,22 @@ export const AI_QUOTA_PAYWALL_STRIPE_CHECKOUT_URL = 'https://buy.stripe.com/7sYe
 
 export const AI_QUOTA_PAYWALL_CONTACT_SALES_EMAIL = 'sales@superblockshq.com';
 
+// TODO: Revisit this mailto template once backend enforcement is in place.
+// Surface the specific reason (buy a seat vs. increase org credits) so the
+// email to the admin is actionable rather than generic.
 export const AI_QUOTA_PAYWALL_CONTACT_SALES_MAILTO = 'mailto:sales@superblockshq.com?subject=Enterprise%20inquiry';
 
 export const AI_QUOTA_PAYWALL_REASON_CONFIG: Record<AiQuotaPaywallReason, { title: string; subtitle: string }> = {
+  credit_limit_exceeded: {
+    title: 'Your organization has reached its AI usage limit',
+    subtitle: 'Ask your admin to purchase additional AI credits to continue using Clark AI.'
+  },
+  no_seat_assigned: {
+    title: "You don't have an AI Builder license",
+    subtitle: 'Ask your admin to assign a license so you can continue building with Clark AI.'
+  },
   token_limit_exceeded: {
-    title: 'Your free trial has ended',
+    title: 'Your organization has reached its AI usage limit',
     subtitle: 'Upgrade your plan to continue using Clark AI and other AI-powered features.'
   },
   trial_expired: {
@@ -35,28 +65,36 @@ export const AI_QUOTA_PAYWALL_REASON_CONFIG: Record<AiQuotaPaywallReason, { titl
   }
 };
 
+export const AI_QUOTA_PAYWALL_PRICE_PER_SEAT_ANNUAL = 80;
+export const AI_QUOTA_PAYWALL_PRICE_PER_SEAT_MONTHLY = 100;
+export const AI_QUOTA_PAYWALL_CREDITS_PER_SEAT = 80;
+export const AI_QUOTA_PAYWALL_APPS_PER_SEAT = 1;
+export const AI_QUOTA_PAYWALL_MIN_SEATS = 1;
+export const AI_QUOTA_PAYWALL_MAX_SEATS = 100;
+
 export const AI_QUOTA_PAYWALL_TEAMS_FEATURES = [
-  '200 AI Credits per AI Builder / month',
+  '80 AI Credits per AI Builder / month',
+  'Org-level credit top-ups, shared across team',
   'Clark AI agent for app building',
   'Clark User Memory',
   'AI Credit Packs add-on available'
 ];
 
 export const AI_QUOTA_PAYWALL_ENTERPRISE_FEATURES = [
-  '200 AI Credits per AI Builder / month',
-  'Org-level credit top-ups, shared across team',
-  'Clark AI agent for app building',
-  'Clark Integration and Organization Memory'
+  'Clark Integration and Organization memory',
+  'Source Control via GitHub, GitLab, BitBucket, Azure DevOps',
+  'Secrets Management',
+  'Embedded Applications',
+  'Custom app hosting'
 ];
 
-export const AI_QUOTA_PAYWALL_TEAMS_PLATFORM_FEATURES = ['Staging and production environments', '50+ integrations'];
+export const AI_QUOTA_PAYWALL_TEAMS_PLATFORM_FEATURES = ['Staging and production environments', '1 hosted app included'];
 
 export const AI_QUOTA_PAYWALL_ENTERPRISE_PLATFORM_FEATURES = [
-  'Source Control via GitHub, GitLab, BitBucket, Azure DevOps',
-  'Custom app hosting with volume pricing',
+  'Deploy in your VPC (Hybrid or Cloud Prem)',
   'SSO / SAML / OIDC',
-  'VPC Deployment',
-  'Audit Logs',
-  'Dedicated support',
-  '99.9% SLA'
+  'Role-based access control (RBAC)',
+  'Audit Logs & Observability'
 ];
+
+export const AI_QUOTA_PAYWALL_ENTERPRISE_SUPPORT_FEATURES = ['Dedicated account team', 'Enterprise Uptime and SLAs'];

package/src/types/billing/billing.ts

@@ -1,7 +1,10 @@
 export enum BillingPlan {
   TRIAL = 'TRIAL',
+  /** @deprecated Legacy v1 plan — no longer issued to new organizations. */
   FREE = 'FREE',
+  /** @deprecated Legacy v1 plan — no longer issued to new organizations. */
   STARTER = 'STARTER',
+  /** @deprecated Legacy v1 plan — no longer issued to new organizations. */
   PRO = 'PRO',
   ENTERPRISE = 'ENTERPRISE',
   TEAMS = 'TEAMS',
@@ -13,4 +16,6 @@ export type Billing = {
   isExpired: boolean;
   expiryDate: Date;
   daysLeft: number;
+  billingInterval?: 'annual' | 'monthly' | null;
+  interval?: 'annual' | 'monthly' | null;
 };

package/src/types/fact/fact.ts

@@ -54,3 +54,21 @@ export type FactListQuery = {
 export interface ListFactsResponse {
   facts: FactDto[];
 }
+
+/**
+ * FactCreate for Socket RPC protocol.
+ *
+ * NOTE: This type is intentionally duplicated from @superblocksteam/schemas to avoid
+ * a circular dependency. The schemas package cannot depend on shared, and the socket
+ * protocol in shared needs this type. Keep in sync with packages/schemas/src/schemas/FactCreate.ts.
+ */
+export type FactCreate = {
+  name: string;
+  description: string;
+  content: string;
+  metadata?: Record<string, unknown>;
+  entityScope: FactEntityScope;
+  entityId: string;
+  accessType?: FactAccessType;
+  createdSource?: FactCreatedSource;
+};

package/src/types/rbac/index.ts

@@ -39,6 +39,7 @@ export enum PermissionedEntities {
   APPLICATION_V2 = 'application_v2',
   API_V3 = 'api_v3',
   API = 'api',
+  ORGANIZATION = 'organization',
   /**
    * @deprecated The Datasource entity is being deprecated in favor of the Integration entity.
    */
@@ -135,6 +136,7 @@ export enum ResourceTypeEnum {
   APPLICATIONS = 'apps',
   APPLICATIONS_APIS = 'apps.apis',
   APPLICATIONS_PAGES = 'apps.pages',
+  BILLING = 'billing',
   FOLDERS = 'folders',
   GROUPS = 'groups',
   GROUPS_MEMBERS = 'groups.members',
@@ -187,6 +189,9 @@ export const ActionTypeByResourceType = {
     READ: ActionTypeEnum.READ,
     MANAGE: ActionTypeEnum.MANAGE
   },
+  BILLING: {
+    MANAGE: ActionTypeEnum.MANAGE
+  },
   WORKFLOWS: {
     DEPLOY: ActionTypeEnum.DEPLOY,
     DELETE: ActionTypeEnum.DELETE,

package/src/utils/attachment-upload.test.ts

@@ -0,0 +1,153 @@
+import { describe, expect, test } from 'vitest';
+import {
+  buildAttachmentUploadMetadata,
+  buildAttachmentUploadFormData,
+  createUploadedAttachmentFromServer,
+  normalizeAttachmentMimeType,
+  toAttachmentUploadDescriptor
+} from './attachment-upload.js';
+
+describe('toAttachmentUploadDescriptor', () => {
+  test('preserves explicit names for non-File uploads', () => {
+    const descriptor = toAttachmentUploadDescriptor({
+      data: 'data:image/webp;base64,Zm9v',
+      mimeType: 'image/webp',
+      name: 'capture.webp'
+    });
+
+    expect(descriptor).toMatchObject({
+      fileName: 'capture.webp',
+      mimeType: 'image/webp'
+    });
+  });
+
+  test('falls back to mime-derived filenames for unnamed non-File uploads', () => {
+    const descriptor = toAttachmentUploadDescriptor({
+      data: 'data:application/pdf;base64,Zm9v',
+      mimeType: 'application/pdf'
+    });
+
+    expect(descriptor).toMatchObject({
+      fileName: 'attachment.pdf',
+      mimeType: 'application/pdf'
+    });
+  });
+
+  test('normalizes browser ts mime types from filename when they are not text-like', () => {
+    const descriptor = toAttachmentUploadDescriptor(new File(['const answer = 42;'], 'main.ts', { type: 'video/mp2t' }));
+
+    expect(descriptor).toMatchObject({
+      fileName: 'main.ts',
+      mimeType: 'text/plain'
+    });
+  });
+});
+
+describe('buildAttachmentUploadFormData', () => {
+  test('appends the normalized filename to form data', () => {
+    const descriptor = toAttachmentUploadDescriptor({
+      data: 'data:image/webp;base64,Zm9v',
+      mimeType: 'image/webp',
+      name: 'capture.webp'
+    });
+
+    expect(descriptor).not.toBeNull();
+
+    const formData = buildAttachmentUploadFormData({
+      descriptor: descriptor!,
+      prefix: 'captured-screenshot'
+    });
+
+    const uploadedFile = formData.get('file');
+    expect(uploadedFile).toBeInstanceOf(File);
+    expect((uploadedFile as File).name).toBe('capture.webp');
+    expect(formData.get('prefix')).toBe('captured-screenshot');
+  });
+
+  test('appends serialized metadata when provided', () => {
+    const descriptor = toAttachmentUploadDescriptor({
+      data: 'data:text/plain;base64,Zm9v',
+      mimeType: 'text/plain',
+      name: 'notes.txt'
+    });
+
+    expect(descriptor).not.toBeNull();
+
+    const formData = buildAttachmentUploadFormData({
+      descriptor: descriptor!,
+      prefix: 'message-attachment',
+      metadata: buildAttachmentUploadMetadata({
+        label: 'Error screenshot',
+        insight: 'Shows a missing submit button'
+      })
+    });
+
+    expect(formData.get('metadata')).toBe(
+      JSON.stringify({
+        label: 'Error screenshot',
+        insight: 'Shows a missing submit button'
+      })
+    );
+  });
+});
+
+describe('createUploadedAttachmentFromServer', () => {
+  test('falls back to the original mime type when the server omits one', () => {
+    const uploadedAttachment = createUploadedAttachmentFromServer({
+      response: {
+        attachmentId: '123',
+        fileName: '',
+        contentUrl: '/api/v1/files/content/123',
+        mimeType: null,
+        purpose: 'attachment',
+        scopeType: 'app',
+        signedUrl: 'https://signed.example/123',
+        signedUrlExpiresAt: '2026-03-06T00:00:00.000Z',
+        storageKey: 'message-attachment/123'
+      },
+      fallbackFileName: 'spec.pdf',
+      fallbackMimeType: 'application/pdf',
+      label: 'Spec',
+      insight: 'Reference doc'
+    });
+
+    expect(uploadedAttachment).toEqual({
+      type: 'uploaded',
+      url: '/api/v1/files/content/123',
+      signedUrl: 'https://signed.example/123',
+      mediaType: 'application/pdf',
+      fileName: 'spec.pdf',
+      label: 'Spec',
+      insight: 'Reference doc',
+      storageKey: 'message-attachment/123',
+      signedUrlExpiresAt: '2026-03-06T00:00:00.000Z',
+      scopeType: 'app',
+      applicationId: undefined
+    });
+  });
+});
+
+describe('buildAttachmentUploadMetadata', () => {
+  test('normalizes non-empty label and insight fields', () => {
+    expect(
+      buildAttachmentUploadMetadata({
+        label: 'Error screenshot',
+        insight: 'Shows a missing submit button'
+      })
+    ).toEqual({
+      label: 'Error screenshot',
+      insight: 'Shows a missing submit button'
+    });
+  });
+});
+
+describe('normalizeAttachmentMimeType', () => {
+  test('prefers text-safe mime types for text-like filenames', () => {
+    expect(
+      normalizeAttachmentMimeType({
+        fileName: 'component.tsx',
+        mimeType: 'video/mp2t'
+      })
+    ).toBe('text/plain');
+  });
+});