Initial import of zappier-edge from zapier monorepo
This commit is contained in:
commit
525edd7469
128 changed files with 20479 additions and 0 deletions
126
docs/ACCOUNTING.md
Normal file
126
docs/ACCOUNTING.md
Normal file
|
|
@ -0,0 +1,126 @@
|
|||
# Company Accounting Walkthrough
|
||||
|
||||
This guide covers the company-side accounting surface: invoicing, purchase-order
|
||||
billing, reports, trends, and CSV export. Everything here runs in the **admin
|
||||
console** at `/admin`.
|
||||
|
||||
> Audience: operations and accounting staff. For pricing and customer setup see
|
||||
> `USER-MANAGEMENT.md`; for the end-user view see `CUSTOMER-PORTAL.md`.
|
||||
|
||||
---
|
||||
|
||||
## 1. Sign in
|
||||
|
||||
Open `http://<host>:<port>/admin` and sign in. The development credentials are
|
||||
`demo` / `$$$Adm1n###` (override with `DEMO_ADMIN_USER` / `DEMO_ADMIN_PASSWORD`;
|
||||
the primary account is `ADMIN_USER` / `ADMIN_KEY`).
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
## 2. Billing identity per customer
|
||||
|
||||
Before invoicing, each customer needs a **billing type** and an **email** — set
|
||||
on the **Customers** tab:
|
||||
|
||||
- **Stripe** — metered usage is reported to Stripe by the daily billing job.
|
||||
- **Purchase order** — invoiced manually with a PO number; issued PO invoices
|
||||
get a 30-day due date automatically.
|
||||
|
||||
|
||||
|
||||
Customers can also carry a **prepaid balance** (funded from the customer
|
||||
portal). When an invoice is issued and the balance fully covers the billable
|
||||
amount, the balance is drawn down and the invoice goes straight to **paid**.
|
||||
Partial coverage is left untouched — there are no partial payments.
|
||||
|
||||
---
|
||||
|
||||
## 3. Generate invoices
|
||||
|
||||
On the **Invoices** tab, pick a **period** (month), optionally narrow to one
|
||||
customer, optionally set a **PO number**, and click **Generate**.
|
||||
|
||||
|
||||
|
||||
Generation rules:
|
||||
|
||||
- One invoice per customer with usage in the period, grouped by endpoint.
|
||||
- The tier **monthly credit** is applied; only the remainder is billable.
|
||||
- Regenerating a period **replaces drafts** (e.g. after late-arriving usage)
|
||||
and **skips issued/paid invoices** — the result panel lists who was skipped
|
||||
and why.
|
||||
- Invoice ids are `INV-<period>-<sequence>`, e.g. `INV-2026-07-0002`.
|
||||
|
||||
## 4. Issue, view, collect
|
||||
|
||||
Each row shows status, billing type, totals, and due amount:
|
||||
|
||||
- **Issue** (draft → issued) — finalizes the invoice; PO invoices get a due
|
||||
date 30 days out. Balance-covered invoices skip straight to **paid**.
|
||||
- **View** — opens the print-ready invoice in a new tab. Use the browser's
|
||||
**Print → Save as PDF** to produce a PDF for the customer.
|
||||
- **Mark paid** (issued → paid) — record collection for PO invoices.
|
||||
|
||||
|
||||
|
||||
Filter the table by customer, period, or status with the filter bar.
|
||||
|
||||
---
|
||||
|
||||
## 5. Reports and trends
|
||||
|
||||
The **Reports** tab answers "who owes what, and how is usage trending?"
|
||||
|
||||
|
||||
|
||||
- **Billing report** — per-customer calls, gross usage, credits applied, and
|
||||
billable amount for a date range. Filter by customer or billing type (all
|
||||
Stripe customers, all PO customers, or one customer). Summary cards total
|
||||
the selection.
|
||||
- **Download CSV** — the same rows as `billing-report.csv` with the active
|
||||
filters, ready for the accounting package.
|
||||
- **Usage trend** — daily or weekly buckets as a bar chart; hover a bar for
|
||||
exact calls and amount.
|
||||
|
||||
The same data is available as JSON/CSV from the API:
|
||||
`GET /admin/api/reports/billing?from=…&to=…&customerId=…&billingType=…&format=csv`
|
||||
and `GET /admin/api/reports/usage-trend?bucket=day|week`.
|
||||
|
||||
---
|
||||
|
||||
## 6. System snapshot
|
||||
|
||||
The **System** tab shows integration health (Zapier app directory, version,
|
||||
triggers, creates) and the current period at a glance: calls, billable amount,
|
||||
open invoice count, and open amount.
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
## 7. Automated Stripe reporting
|
||||
|
||||
A daily job (`src/jobs/report-usage.ts`, scheduled separately) reports the
|
||||
billable delta of every Stripe-billed customer to Stripe Billing meter events.
|
||||
It is idempotent: a ledger records the cumulative reported cents per customer
|
||||
per period, and only the delta since the last successful run is sent. PO
|
||||
customers are excluded by having no `stripeCustomerId`.
|
||||
|
||||
Environment (`.env` at the project root):
|
||||
|
||||
```
|
||||
STRIPE_SECRET_KEY=sk_live_or_test_...
|
||||
ZAPPIER_DB=/absolute/path/to/zappier.db # optional
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Data notes
|
||||
|
||||
- Money is integer **cents** everywhere internally; the UI formats dollars.
|
||||
- All accounting data lives in the SQLite database (`zappier.db` by default):
|
||||
`invoices`, `invoice_lines`, `billing_ledger`, `customers`.
|
||||
- The Stripe billing job and the admin console can run from any working
|
||||
directory — all paths resolve from the installation root.
|
||||
Loading…
Add table
Add a link
Reference in a new issue