osome

Osome Automation Skill

Automate document uploads and invoice management for Osome, a corporate secretary and accounting platform for Singapore companies.

What This Skill Does

Osome flags bank transactions that need supporting documents (invoices, receipts, salary slips). Their web UI requires uploading each document one by one. This skill automates the entire workflow:

1. List transactions that need documents attached
2. Generate missing PDFs (salary slips, client invoices, receipts) from data using Puppeteer
3. Upload documents via Osome's internal API (presigned S3 URLs)
4. Link documents to transactions and send messages to accounting threads

Prerequisites

• Bun runtime
• A valid Osome account with browser session cookies
• Puppeteer (for PDF generation)

Setup

# Install dependencies
bun install

# Copy env template and add your Osome cookies
cp .env.example .env
# Edit .env — paste cookies from browser DevTools → Network → any Osome request → Cookie header

How to Get Your Cookies

1. Log into my.osome.com in your browser
2. Open DevTools (Cmd+Shift+I) → Network tab
3. Click on any request to my.osome.com
4. Copy the Cookie header value
5. Paste into .env as OSOME_COOKIES

CLI Commands

bun scripts/osome.ts list                              # List transactions needing documents
bun scripts/osome.ts upload <txId> <file> [-m "msg"]   # Upload PDF and link to transaction
bun scripts/osome.ts message <txId> <message>          # Send message to transaction thread
bun scripts/osome.ts tx <txId>                         # Get transaction details

API Reference

All endpoints use https://my.osome.com/api/v2 with session cookie authentication.

List Transactions

GET /roberto/companies/{COMPANY_ID}/transactions?sort=dateDesc&perPage=200&page=1

Filter response for transactionStatus === "documentRequired".

Upload Flow (3 Steps)

Step 1 — Get presigned S3 URL:

POST /companies/{COMPANY_ID}/files/url_for_upload
Body: { filename, size, contentType, checksum (MD5 hex) }
Returns: { uploadUrlInfo: { signedUrl, formData }, file: { url, signedUrl } }

Step 2 — Upload file to S3:

POST {signedUrl from step 1}
Body: FormData with all formData fields from step 1, then file LAST

Important: The file field MUST be appended last in the FormData. S3 presigned POST uploads enforce this ordering.

Step 3 — Create document and link to transaction:

POST /companies/{COMPANY_ID}/documents
Body: {
  document: {
    attributes: { acTransactionIds: [txId] },
    uploadingMethod: "transactionItemPage",
    name: filename,
    file: { url, signedUrl, name, fileSize, checksum }
  }
}

Send Message

POST /conversations/{CONVERSATION_ID}/messages
Body: { message: { text: "your message" } }

PDF Generation

Generate missing invoices/receipts from transaction data using Puppeteer:

bun scripts/generate-salary-pdfs.ts        # Salary payment slips
bun scripts/generate-client-invoices.ts    # Client invoices
bun scripts/generate-visa-receipt.ts       # Visa receipts

Each generator:

1. Takes an array of payment data (txId, date, amount, name, etc.)
2. Renders an HTML template with inline CSS
3. Converts to PDF via page.pdf({ format: "A4" })
4. Outputs a mapping.json linking { txId, filename } pairs

Bulk Upload Pattern

for entry in $(cat salary-pdfs/mapping.json | jq -c '.[]'); do
  txId=$(echo $entry | jq -r '.txId')
  file=$(echo $entry | jq -r '.filename')
  bun scripts/osome.ts upload $txId $file -m "Document attached"
done

Project Structure

├── lib/
│   ├── api/
│   │   ├── osome.ts      # Core API functions
│   │   ├── upload.ts      # S3 upload helper
│   │   └── types.ts       # TypeScript interfaces + constants
│   └── utils/
│       └── md5.ts         # MD5 checksum (pure JS, RFC 1321)
├── scripts/
│   ├── osome.ts           # CLI tool
│   └── generate-*.ts      # PDF generators (customize with your data)
├── .env.example           # Environment template
└── package.json

Customization

To use this for your own Osome account:

1. Update COMPANY_ID in lib/api/types.ts with your company ID (visible in Osome URLs)
2. Modify the payment data arrays in generate-*.ts scripts with your transactions
3. Customize HTML templates for your company branding

Key Technical Details

• Auth: Session cookies only (no API keys or OAuth)
• Storage: Osome uses S3 in ap-southeast-1 for document storage
• File integrity: MD5 checksums required for all uploads
• Rate limits: No observed rate limits, but paginate transactions (200 per page)
• Internal naming: Osome's frontend is called "websome" internally (x-initiator: websome-transactions@x.x.x)