# Osome

> Automate document uploads and transaction management for Osome accounting platform (Singapore). Use when: user mentions Osome, needs to upload invoices/receipts to Osome, wants to generate PDF invoices, or needs to interact with Osome's internal API. Covers the full workflow: list transactions needing documents, generate missing PDFs from data, upload via presigned S3 URLs, and link documents to transactions.

- Skill: `necmttn/osome` (Agent Skill, multi-file: 5 files)
- Install (CLI): `npx skillmds@latest add necmttn/osome`
- Raw SKILL.md: https://api.skillmd.com/api/skills/necmttn/osome/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: Necmttn (https://skillmd.com/u/necmttn)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/necmttn/osome

---


# Osome Automation Skill

Automate document uploads and invoice management for [Osome](https://osome.com), 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](https://bun.sh) runtime
- A valid Osome account with browser session cookies
- Puppeteer (for PDF generation)

## Setup

```bash
# 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

```bash
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:

```bash
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

```bash
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`)