Milestone 1: Add Numbers Zapier app, /v1/add, developer setup guide
packages/verae-activate is pushable with zapier-platform 19.1.0: local Add Numbers (number1+number2=sum) needs no hosted API. zapier-platform validate is clean (0 warnings). zappier POST /v1/add is a free metered endpoint for the optional hosted path. Tests: verae-activate 7/7, zappier 176/176, verae-zapier 5/5, middleware gate 1 11/11. Morning steps: docs/04-activate/SETUP-ZAPIER-DEVELOPER.md Learned: perform runs on Zapier cloud so arithmetic needs no public URL; CLI and zapier-platform-core majors must match; do not mix zapier-sdk.
This commit is contained in:
parent
b4150c8250
commit
b814501441
18 changed files with 1452 additions and 1 deletions
6
docs/04-activate/README.md
Normal file
6
docs/04-activate/README.md
Normal file
|
|
@ -0,0 +1,6 @@
|
|||
# Activate now
|
||||
|
||||
1. Morning checklist: [SETUP-ZAPIER-DEVELOPER.md](SETUP-ZAPIER-DEVELOPER.md)
|
||||
2. App: `packages/verae-activate` — action **Add Numbers**
|
||||
3. Tests: `cd packages/verae-activate && npm test`
|
||||
4. Validate: `zapier-platform validate` (already structurally sound)
|
||||
173
docs/04-activate/SETUP-ZAPIER-DEVELOPER.md
Normal file
173
docs/04-activate/SETUP-ZAPIER-DEVELOPER.md
Normal file
|
|
@ -0,0 +1,173 @@
|
|||
# Set up a Zapier Developer account and push Verae Time (tomorrow)
|
||||
|
||||
This is the only document you need in the morning to **create a Zapier developer account**, **push Verae Time**, and **run Add Numbers** (`number1` + `number2` → `sum`). No Verae servers, no NATS, no public URL.
|
||||
|
||||
App path: `packages/verae-activate`
|
||||
|
||||
---
|
||||
|
||||
## 0. What you will have when this works
|
||||
|
||||
1. A Zapier developer account (free).
|
||||
2. A private integration named **Verae Time**.
|
||||
3. A Zap: any trigger (e.g. Schedule) → **Verae Time → Add Numbers**.
|
||||
4. A test that shows `2 + 3 = 5`.
|
||||
|
||||
After that, we grow the same integration into timestamping. Do **not** mix this with `zapier-sdk` (that consumes other people’s apps). We use **`zapier-platform`** to *publish* ours.
|
||||
|
||||
---
|
||||
|
||||
## 1. Create the Zapier account (browser, ~5 minutes)
|
||||
|
||||
1. Open [https://zapier.com/sign-up](https://zapier.com/sign-up) and create an account (Google/SSO is fine).
|
||||
2. Confirm email if asked.
|
||||
3. Open the Platform: [https://developer.zapier.com](https://developer.zapier.com)
|
||||
Same login. This is **Zapier Platform**, not the 8,000-app consumer directory yet.
|
||||
4. You should land on **My Integrations** (empty is fine).
|
||||
|
||||
If you already have a Zapier account from using Zaps, skip sign-up and go straight to developer.zapier.com.
|
||||
|
||||
---
|
||||
|
||||
## 2. Install the CLI on this Mac (Terminal)
|
||||
|
||||
The CLI is already on this machine as `zapier-platform` (v19.1.0) in `~/.npm-global/bin`. In a new terminal:
|
||||
|
||||
```bash
|
||||
export PATH="$HOME/.npm-global/bin:$PATH"
|
||||
zapier-platform --version
|
||||
```
|
||||
|
||||
You want **19.x**. If the command is missing:
|
||||
|
||||
```bash
|
||||
npm install -g zapier-platform-cli
|
||||
export PATH="$HOME/.npm-global/bin:$PATH"
|
||||
zapier-platform --version
|
||||
```
|
||||
|
||||
Do **not** use the old `zapier` binary if it is a different major from `zapier-platform-core` in the app (`19.1.0`).
|
||||
|
||||
---
|
||||
|
||||
## 3. Log the CLI into your account
|
||||
|
||||
```bash
|
||||
zapier-platform login
|
||||
```
|
||||
|
||||
A browser window opens. Approve the deploy key. This writes `~/.zapierrc` (never commit that file).
|
||||
|
||||
SSO-only org:
|
||||
|
||||
```bash
|
||||
zapier-platform login --sso
|
||||
```
|
||||
|
||||
Check:
|
||||
|
||||
```bash
|
||||
zapier-platform whoami
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. Register and push Verae Time
|
||||
|
||||
```bash
|
||||
cd /Users/marchon/apps/zapier/packages/verae-activate
|
||||
npm install
|
||||
npm test
|
||||
zapier-platform validate
|
||||
zapier-platform register "Verae Time"
|
||||
zapier-platform push
|
||||
```
|
||||
|
||||
`register` creates the integration and writes `.zapierapprc` (app id). **Do commit `.zapierapprc`** after register so the next push knows which app to update. **Do not commit** `~/.zapierrc`.
|
||||
|
||||
`push` uploads a **private** version. It is only visible to your account until you invite others.
|
||||
|
||||
If `register` says the name is taken, use `"Verae Time Dev"` or `"VeraeTime"`.
|
||||
|
||||
---
|
||||
|
||||
## 5. Enable the integration in the Zap editor
|
||||
|
||||
1. Open [https://zapier.com/app/zaps](https://zapier.com/app/zaps) → **Create**.
|
||||
2. **Trigger:** *Schedule by Zapier* → Every hour (or *Zapier Chrome extension* / any trigger you like). You only need something that can fire a test.
|
||||
3. **Action:** search **Verae Time**. If it does not appear:
|
||||
- In the Zap editor app search, open **Change account** / custom integrations.
|
||||
- Or visit [https://developer.zapier.com](https://developer.zapier.com) → your app → **Sharing** and confirm it is available to your user.
|
||||
- Hard refresh. Private apps can take a minute after the first push.
|
||||
4. **Connect** Verae Time:
|
||||
- **API Key** — leave **blank**.
|
||||
- **API base URL** — leave **blank**.
|
||||
- Test connection → should succeed (*Verae Time (Add Numbers)* / local mode).
|
||||
5. Choose action **Add Numbers**.
|
||||
6. Set **Number 1** = `2`, **Number 2** = `3`.
|
||||
7. **Test step**. You want:
|
||||
|
||||
```json
|
||||
{
|
||||
"number1": 2,
|
||||
"number2": 3,
|
||||
"sum": 5,
|
||||
"mode": "local"
|
||||
}
|
||||
```
|
||||
|
||||
Turn the Zap on if you want it to keep running. Failures on Zapier are free; successes count as tasks.
|
||||
|
||||
---
|
||||
|
||||
## 6. Optional: point Add Numbers at your hosted zappier API
|
||||
|
||||
Only after `packages/zappier` is reachable on the public internet (ngrok, fly, etc.):
|
||||
|
||||
1. Sign up in `packages/zappier` portal (`/portal`) → copy API key.
|
||||
2. In the Zapier connection, set:
|
||||
- API Key = that key
|
||||
- API base URL = `https://<your-host>` (no trailing path)
|
||||
3. Re-test. `mode` becomes `"hosted"` and `POST /v1/add` is metered (list price **free**).
|
||||
|
||||
Until then, leave both fields empty.
|
||||
|
||||
---
|
||||
|
||||
## 7. If something fails
|
||||
|
||||
| Symptom | Fix |
|
||||
|---------|-----|
|
||||
| `zapier-platform: command not found` | `export PATH="$HOME/.npm-global/bin:$PATH"` |
|
||||
| `Not logged in` | `zapier-platform login` |
|
||||
| `validate` schema error | Stay on `zapier-platform-core@19.1.0` matching CLI 19.x |
|
||||
| App not in Zap editor | Push succeeded? Check developer.zapier.com versions. Search “Verae”. |
|
||||
| Connection test fails with blank keys | You are on an old push; `git pull` / push again. Local test does not HTTP. |
|
||||
| `ENOTFOUND` / timeout on test | You filled API base URL. Clear it for Add Numbers. |
|
||||
| Invite a teammate | developer.zapier.com → app → Sharing → invite email |
|
||||
|
||||
---
|
||||
|
||||
## 8. What this is *not*
|
||||
|
||||
- This is **not** `zapier-sdk` and **not** Zapier MCP.
|
||||
- This does **not** yet timestamp on `api.veraetime.net`. That is `packages/verae-zapier` + middleware, next after Add Numbers is green on your account.
|
||||
- Do not put Verae JWTs in Zapier. Keys, when you use them, are zappier portal keys.
|
||||
|
||||
---
|
||||
|
||||
## 9. Commands cheat sheet
|
||||
|
||||
```bash
|
||||
export PATH="$HOME/.npm-global/bin:$PATH"
|
||||
cd /Users/marchon/apps/zapier/packages/verae-activate
|
||||
|
||||
npm test
|
||||
zapier-platform whoami
|
||||
zapier-platform validate
|
||||
zapier-platform push # after the first register
|
||||
zapier-platform versions
|
||||
zapier-platform logs
|
||||
```
|
||||
|
||||
Official CLI docs: [https://docs.zapier.com/platform/reference/cli-docs](https://docs.zapier.com/platform/reference/cli-docs)
|
||||
22
docs/WORK-LOG.md
Normal file
22
docs/WORK-LOG.md
Normal file
|
|
@ -0,0 +1,22 @@
|
|||
# Work log
|
||||
|
||||
Running record of milestones. Ordered by dependency.
|
||||
|
||||
| ID | Item | Depends on | Status |
|
||||
|----|------|------------|--------|
|
||||
| M0 | Import zappier + middleware + research; git checkin | — | done `b4150c8` |
|
||||
| M1 | Organize layout + activate app + tests + Zapier setup guide | M0 | in progress |
|
||||
| M2 | Git checkin after green tests | M1 | pending |
|
||||
| M3 | Per-module MD (params, callees, returns) | M2 | pending |
|
||||
| M4 | Sphinx + PDF for every module | M3 | pending |
|
||||
| M5 | Git checkin docs + lessons | M4 | pending |
|
||||
| M6 | Integration hardening (`/v1/add` already on zappier) | M2 | partial |
|
||||
| M7 | Ready-to-activate final checkin | M5 | pending |
|
||||
|
||||
## Learned (M1)
|
||||
|
||||
- Zapier Platform `perform` runs in Zapier cloud. Add Numbers can be pure arithmetic so a first push needs **no public URL**.
|
||||
- CLI on this machine is `zapier-platform` 19.x; app core must match (`19.1.0`).
|
||||
- `zapier-platform validate` is structurally sound for `packages/verae-activate`.
|
||||
- Hosted path is optional: zappier `POST /v1/add` is free on the rate card (`operationId: add`).
|
||||
- Do not mix `zapier-sdk` (consume) with `zapier-platform` (publish).
|
||||
Loading…
Add table
Add a link
Reference in a new issue