Build on Upload Native

// Get a File from an <input type="file"> (or a drop event's dataTransfer.files).
const input = document.querySelector<HTMLInputElement>('#proof');

input?.addEventListener('change', () => {
  const file: File | undefined = input.files?.[0];
  if (file) void handleUpload(file);
});

import type { UploadRef } from './types';

// Upload the bytes straight to Shopify Files, then attach the reference to the cart.
async function handleUpload(file: File): Promise<void> {
  const cart: { token: string } = await fetch('/cart.js').then((r) => r.json());

  const ref: UploadRef = await UploadNative.upload(file, {
    base: '/apps/upload-app',          // the app proxy (HMAC-verified by the server)
    allowed: ['application/pdf', 'image/*'],
    reference: cart.token,             // opaque order reference, no PII
    onProgress: (loaded: number, total: number): void => {
      setProgress(Math.round((loaded / total) * 100));
    },
  });

  await UploadNative.attach(ref, { target: 'cart_attribute' });
}

// Without the attach() helper: write the cart attribute yourself.
await fetch('/cart/update.js', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    attributes: {
      upload_reference: ref.fileUrl,
      upload_reference_ids: ref.fileId,
    },
  }),
});

// Attach the uploaded file to a cart LINE-ITEM property (per product), so it
// shows on the order's line item. Shopify does NOT auto-hotlink the URL — your
// theme renders the link (see the cart-template Liquid below).
//
// Option A — let the SDK write it onto the add-to-cart form:
const form = document.querySelector('form[action*="/cart/add"]');
const ref = await UploadNative.upload(file, { base: '/apps/upload-app' });
await UploadNative.attach(ref, { target: 'line_item_property', form });
// → properties[Uploaded file] = <file URL>             (shown on the order)
//   properties[_upload_reference_ids] = <file GID>     (hidden: leading "_")

// Hide the file line from the cart & checkout (still kept on the order):
await UploadNative.attach(ref, { target: 'line_item_property', form, hidden: true });
// → properties[_Uploaded file] = <file URL>            (leading "_" hides it from shoppers)

// Option B — write the hidden input yourself before the native add-to-cart submit.
// (The URL alone is enough to hotlink it; the SDK additionally writes the hidden
//  properties[_upload_reference_ids] GID companion, which this variant omits.)
const input = document.createElement('input');
input.type = 'hidden';
input.name = 'properties[Uploaded file]';
input.value = ref.fileUrl;       // the Shopify Files CDN URL
form.appendChild(input);

{%- comment -%} In your theme's cart template / cart line items {%- endcomment -%}
{% for property in item.properties %}
  {%- if property.last == blank -%}{%- continue -%}{%- endif -%}
  {{ property.first }}:
  {% if property.last contains '/cdn.shopify.com/' or property.last contains '/uploads/' %}
    <a href="{{ property.last }}" target="_blank" rel="noopener">{{ property.last | split: '/' | last }}</a>
  {% else %}
    {{ property.last }}
  {% endif %}
{% endfor %}

// window.UploadNative: available once the app embed (or a block) mounts.
interface UploadNative {
  upload(file: File, options: UploadOptions): Promise<UploadRef>;
  uploadMany(files: File[], options: UploadManyOptions): Promise<SettledResult<UploadRef>[]>;
  validate(file: File, options: ValidateOptions): string | null; // null = ok
  attach(refs: UploadRef | UploadRef[], options?: AttachOptions): Promise<void>;
  init(root?: ParentNode): void;        // no-op; blocks self-render, kept for compatibility
  readonly version: string;
}

interface UploadRef {
  fileId: string;   // Shopify File GID, e.g. "gid://shopify/GenericFile/123"
  fileUrl: string;  // CDN URL of the stored file
}

interface UploadOptions {
  base: string;                                   // app proxy path, "/apps/upload-app"
  allowed?: string[];                             // MIME types / extensions
  reference?: string;                             // cart token (opaque, no PII)
  onProgress?: (loaded: number, total: number) => void;
  signal?: AbortSignal;                           // cancel an in-flight upload
}

interface UploadManyOptions extends Omit<UploadOptions, 'onProgress'> {
  concurrency?: number;                           // default 3
  onProgress?: (loaded: number, total: number) => void; // aggregate across files
  onFileDone?: (index: number, result: SettledResult<UploadRef>) => void;
}

interface AttachOptions {
  target?: 'cart_attribute' | 'line_item_property'; // default "cart_attribute"
  name?: string;                                  // attribute/property key, default "upload_reference"
  multiple?: boolean;                             // default refs.length > 1
  form?: Element;                                 // required for line_item_property
  hidden?: boolean;                               // line_item_property only: _-prefix the property
                                                  //   so it stays on the order but is hidden from
                                                  //   the cart & checkout. default false
}

interface ValidateOptions {
  accept: string;     // e.g. ".pdf,image/*"
  maxBytes: number;
  maxFiles: number;
}

type SettledResult<T> =
  | { status: 'fulfilled'; value: T }
  | { status: 'rejected'; reason: unknown };

// Events bubble from <upload-native-block> to document; detail carries blockId.
document.addEventListener('upload-native:success', (e: Event) => {
  const { fileId, fileUrl, name } = (e as CustomEvent).detail;
  console.log('uploaded', name, fileUrl, fileId);
});

document.addEventListener('upload-native:error', (e: Event) => {
  const { name, message } = (e as CustomEvent).detail;
  console.warn('failed', name, message);
});

const err: string | null = UploadNative.validate(file, {
  accept: '.pdf,image/*',
  maxBytes: 20 * 1024 * 1024,    // client cap; Shopify Files caps generic files at 20 MB
  maxFiles: 1,
});
if (err) showError(err); // null means the file is acceptable