@pinooxhq/pinion-client

@pinooxhq/pinion-client

Browser client for the Pinion resumable upload protocol.

Works with or without Axios — fetch by default, Axios when you already use it.

Quick start

npm install @pinooxhq/pinion-client

import { uploadFile } from '@pinooxhq/pinion-client';

await uploadFile(file, {
  baseURL: '/api/pinion',
  unwrapPreset: 'pinoox',
  onProgress: ({ percent }) => console.log(percent + '%'),
});

That is the whole idea: init → upload parts → complete — handled for you.

Table of contents

• Quick start
• Features
• Install
• Ways to use
  • 1 — One function
  • 2 — Fluent API
  • 3 — Full client
  • 4 — Low-level steps
  • 5 — With Axios
  • 6 — Custom transport
• Transport
• Framework patterns
• Advanced
• HTTP rules
• API reference
• Publish to npm
• Troubleshooting
• License

Features

Install

# fetch only (recommended)
npm install @pinooxhq/pinion-client

# with Axios (optional peer dependency)
npm install @pinooxhq/pinion-client axios

yarn add @pinooxhq/pinion-client
pnpm add @pinooxhq/pinion-client

Requires Node.js 18+ or a modern browser with fetch.

Ways to use

Pick the style that fits your project — from one-liner to full control.

1 — One function (fastest)

Best for a single upload button. No setup object needed.

import { uploadFile } from '@pinooxhq/pinion-client';

const result = await uploadFile(file, {
  baseURL: '/api/pinion',
  unwrapPreset: 'pinoox',
  parallel: 2,
  onProgress: ({ percent }) => bar.style.width = percent + '%',
});

Skip Pinion for small files and fall back to a normal POST:

const skipped = await uploadFile(file, {
  baseURL: '/api/pinion',
  auto: true,
  threshold: 8 * 1024 * 1024,
});

if (skipped === null) {
  // file is below threshold — use a regular upload
}

With Axios (legacy signature):

import axios from 'axios';
import { uploadFile } from '@pinooxhq/pinion-client';

await uploadFile(axios, file, { baseURL: '/api/pinion', unwrapPreset: 'pinoox' });

2 — Fluent API (reusable)

Create one uploader, use it for many files.

import { pinion } from '@pinooxhq/pinion-client';

const uploader = pinion({
  baseURL: '/app/pinion',
  unwrapPreset: 'pinoox',
  headers: { Authorization: 'Bearer …' },
});

if (!uploader.for(file).needsPinion()) {
  return fallbackUpload(file);
}

await uploader.for(file).upload({ parallel: 2, retry: 2 });

3 — Full client (batch + hooks)

Maximum control — progress hooks, batch uploads, cancel.

import { createPinionFetch } from '@pinooxhq/pinion-client';

const client = createPinionFetch({
  baseURL: '/api/pinion',
  unwrapPreset: 'pinoox',
  destination: 'uploads/media',
  extensions: ['mp4', 'zip', 'pdf'],
});

await client.upload(file, {
  onProgress: ({ percent, bytesUploaded, bytesTotal, speed, eta }) => {
    console.log(`${percent}% · ${speed} B/s · ETA ${eta}s`);
  },
  onChunkStart: (i) => console.log('part', i),
  onError: (err, i) => console.warn(err.code, i),
});

await client.uploadMany([file1, file2], {
  fileParallel: 1,
  onFileStart: (f, i) => console.log('file', i, f.name),
  onFileComplete: (f, result, i) => console.log('done', i),
});

client.cancel();

4 — Low-level steps (manual)

Call each HTTP step yourself — useful for custom UI or non-file sources.

import { createPinionFetch, sha256Hex } from '@pinooxhq/pinion-client';

const client = createPinionFetch({ baseURL: '/api/pinion', unwrapPreset: 'pinoox' });

const session = await client.api.init({
  filename: file.name,
  size: file.size,
  fingerprint: client.buildFingerprint(file),
});

const blob = file.slice(0, session.chunk_size);
const form = new FormData();
form.append('upload_id', session.id);
form.append('index', '0');
form.append('chunk_hash', await sha256Hex(blob));
form.append('chunk', blob);

await client.api.uploadPart(form);
await client.api.complete(session.id);

5 — With Axios (optional)

Use Axios when you need per-chunk onUploadProgress or already have an Axios instance.

import axios from 'axios';
import { pinion, createPinionAxios } from '@pinooxhq/pinion-client';

// shortcut
const uploader = pinion(axios, { baseURL: '/api/pinion', unwrapPreset: 'pinoox' });

await uploader.for(file).upload({
  onProgress: ({ percent }) => console.log(percent),
  onUploadProgress: (event, index) => console.log('part', index, event.loaded),
});

// or get both axios instance + client
const { axios: http, client } = createPinionAxios(axios, {
  baseURL: '/api/pinion',
  unwrapPreset: 'pinoox',
  axiosConfig: { timeout: 120000 },
});

6 — Custom transport

Plug in your own HTTP layer by implementing get, postJson, postForm.

import { createPinionClient, createFetchTransport } from '@pinooxhq/pinion-client';

const transport = createFetchTransport({
  baseURL: '/api/pinion',
  fetch: myFetch,
  unwrap: (res) => res.data,
  headers: { 'X-App': 'portal' },
});

const client = createPinionClient({ transport });

Transport

Check active mode: client.transport.kind → 'fetch' or 'axios'.

Framework patterns

Vue 3

import { ref } from 'vue';
import { pinion } from '@pinooxhq/pinion-client';

const percent = ref(0);
const uploader = pinion({ baseURL: '/app/pinion', unwrapPreset: 'pinoox' });

async function onPick(file) {
  percent.value = 0;
  await uploader.for(file).upload({
    parallel: 2,
    onProgress: (p) => { percent.value = p.percent; },
  });
}

React

import { useState, useMemo } from 'react';
import { createPinionFetch } from '@pinooxhq/pinion-client';

export function usePinion(baseURL = '/api/pinion') {
  const client = useMemo(
    () => createPinionFetch({ baseURL, unwrapPreset: 'pinoox' }),
    [baseURL],
  );
  const [progress, setProgress] = useState(0);

  const upload = (file) => client.for(file).upload({
    onProgress: (p) => setProgress(p.percent),
  });

  return { upload, progress, cancel: () => client.cancel() };
}

Advanced

Unwrap presets

Map your backend JSON envelope without custom code.

import { createPinionClient, unwrapPresets } from '@pinooxhq/pinion-client';

createPinionClient({ baseURL: '/api/pinion', unwrapPreset: 'pinoox' });

createPinionClient({
  baseURL: '/api/pinion',
  unwrap: (res) => res.data.result,
});

unwrapPresets.pinoox(response);

Cancel upload

const controller = new AbortController();
uploader.for(file).upload({ signal: controller.signal });
controller.abort();

// or
uploader.cancel();

HTTP rules

API reference

Factories

Client options

Upload options

Client methods

Transport helpers

Publish to npm

Prerequisites

Steps

cd packages/pinion/client
npm pack                    # verify tarball
npm login
npm version minor -m "chore: release v%s"
npm publish --access public

Verify:

mkdir /tmp/pinion-test && cd /tmp/pinion-test
npm init -y
npm install @pinooxhq/pinion-client

import { pinion, PROTOCOL } from '@pinooxhq/pinion-client';
console.log(PROTOCOL); // pinion

CI (optional)

name: Publish npm
on:
  release:
    types: [published]
jobs:
  publish:
    runs-on: ubuntu-latest
    defaults:
      run:
        working-directory: client
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
          registry-url: https://registry.npmjs.org
      - run: npm ci
      - run: npm publish --access public
        env:
          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

Troubleshooting

License

MIT — Pinoox

PHP protocol: pinoox/pinion