Skip to content

Commit 4ae63cc

Browse files
ph33nxph33nx
committed
feat: autopilot Postman collection sync from OpenAPI specs
0 parents  commit 4ae63cc

38 files changed

Lines changed: 131049 additions & 0 deletions

‎.github/workflows/ci.yml‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
name: CI
2+
3+
on:
4+
pull_request:
5+
push:
6+
branches: [main]
7+
8+
permissions:
9+
contents: read
10+
11+
jobs:
12+
check:
13+
runs-on: ubuntu-latest
14+
steps:
15+
- uses: actions/checkout@v6
16+
17+
- uses: oven-sh/setup-bun@v2
18+
19+
- run: bun install --frozen-lockfile
20+
21+
- name: Lint and format
22+
run: bunx biome ci .
23+
24+
- name: Typecheck
25+
run: bun typecheck
26+
27+
- name: Validate discovery and conversion (no Postman writes)
28+
run: bun run sync --dry-run

‎.github/workflows/sync.yml‎

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
name: Sync collections
2+
3+
on:
4+
schedule:
5+
- cron: '0 6 * * *'
6+
workflow_dispatch:
7+
inputs:
8+
force:
9+
description: 'Rebuild and publish every collection regardless of diff'
10+
type: boolean
11+
default: false
12+
repository_dispatch:
13+
types: [openapi-updated]
14+
15+
permissions:
16+
contents: write
17+
18+
concurrency:
19+
group: sync
20+
cancel-in-progress: false
21+
22+
jobs:
23+
sync:
24+
runs-on: ubuntu-latest
25+
steps:
26+
- uses: actions/checkout@v6
27+
28+
- uses: oven-sh/setup-bun@v2
29+
30+
- run: bun install --frozen-lockfile
31+
32+
- name: Sync to Postman
33+
run: bun run sync ${{ (github.event_name == 'workflow_dispatch' && inputs.force) && '--force' || '' }}
34+
env:
35+
POSTMAN_API_KEY: ${{ secrets.POSTMAN_API_KEY }}
36+
37+
- name: Commit regenerated specs, collections and UID cache
38+
run: |
39+
git config user.name "github-actions[bot]"
40+
git config user.email "github-actions[bot]@users.noreply.github.com"
41+
git add specs collections collections.json
42+
if git diff --cached --quiet; then
43+
echo "No collection changes."
44+
else
45+
git commit -m "sync: update collections from live OpenAPI spec"
46+
git push
47+
fi

‎.gitignore‎

Lines changed: 145 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,145 @@
1+
# Logs
2+
logs
3+
*.log
4+
npm-debug.log*
5+
yarn-debug.log*
6+
yarn-error.log*
7+
lerna-debug.log*
8+
9+
# Diagnostic reports (https://nodejs.org/api/report.html)
10+
report.[0-9]*.[0-9]*.[0-9]*.[0-9]*.json
11+
12+
# Runtime data
13+
pids
14+
*.pid
15+
*.seed
16+
*.pid.lock
17+
18+
# Directory for instrumented libs generated by jscoverage/JSCover
19+
lib-cov
20+
21+
# Coverage directory used by tools like istanbul
22+
coverage
23+
*.lcov
24+
25+
# nyc test coverage
26+
.nyc_output
27+
28+
# Grunt intermediate storage (https://gruntjs.com/creating-plugins#storing-task-files)
29+
.grunt
30+
31+
# Bower dependency directory (https://bower.io/)
32+
bower_components
33+
34+
# node-waf configuration
35+
.lock-wscript
36+
37+
# Compiled binary addons (https://nodejs.org/api/addons.html)
38+
build/Release
39+
40+
# Dependency directories
41+
node_modules/
42+
jspm_packages/
43+
44+
# Snowpack dependency directory (https://snowpack.dev/)
45+
web_modules/
46+
47+
# TypeScript cache
48+
*.tsbuildinfo
49+
50+
# Optional npm cache directory
51+
.npm
52+
53+
# Optional eslint cache
54+
.eslintcache
55+
56+
# Optional stylelint cache
57+
.stylelintcache
58+
59+
# Optional REPL history
60+
.node_repl_history
61+
62+
# Output of 'npm pack'
63+
*.tgz
64+
65+
# Yarn Integrity file
66+
.yarn-integrity
67+
68+
# dotenv environment variable files
69+
.env
70+
.env.*
71+
!.env.example
72+
73+
# parcel-bundler cache (https://parceljs.org/)
74+
.cache
75+
.parcel-cache
76+
77+
# Next.js build output
78+
.next
79+
out
80+
81+
# Nuxt.js build / generate output
82+
.nuxt
83+
dist
84+
.output
85+
86+
# Gatsby files
87+
.cache/
88+
# Comment in the public line in if your project uses Gatsby and not Next.js
89+
# https://nextjs.org/blog/next-9-1#public-directory-support
90+
# public
91+
92+
# vuepress build output
93+
.vuepress/dist
94+
95+
# vuepress v2.x temp directory
96+
.temp
97+
98+
# Sveltekit cache directory
99+
.svelte-kit/
100+
101+
# vitepress build output
102+
**/.vitepress/dist
103+
104+
# vitepress cache directory
105+
**/.vitepress/cache
106+
107+
# Docusaurus cache and generated files
108+
.docusaurus
109+
110+
# Serverless directories
111+
.serverless/
112+
113+
# FuseBox cache
114+
.fusebox/
115+
116+
# DynamoDB Local files
117+
.dynamodb/
118+
119+
# Firebase cache directory
120+
.firebase/
121+
122+
# TernJS port file
123+
.tern-port
124+
125+
# Stores VSCode versions used for testing VSCode extensions
126+
.vscode-test
127+
128+
# pnpm
129+
.pnpm-store
130+
131+
# yarn v3
132+
.pnp.*
133+
.yarn/*
134+
!.yarn/patches
135+
!.yarn/plugins
136+
!.yarn/releases
137+
!.yarn/sdks
138+
!.yarn/versions
139+
140+
# Vite files
141+
vite.config.js.timestamp-*
142+
vite.config.ts.timestamp-*
143+
.vite/
144+
145+
CLAUDE.md

‎AGENTS.md‎

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
# RoxyAPI Postman Collections - Maintainer Guide
2+
3+
This repo publishes the RoxyAPI catalog to a public Postman workspace. It is fully autopilot. Read this before changing anything.
4+
5+
## The one rule
6+
7+
Do not hand edit `collections/`, `specs/`, or `collections.json`. They are generated. The OpenAPI specs at `roxyapi.com` are the single source of truth. To change a collection, change the API, not this repo.
8+
9+
## Adding a domain
10+
11+
Nothing to do here. When a new domain ships and starts serving `https://roxyapi.com/api/v2/{slug}/openapi.json`, the next sync discovers it, creates a collection, records its UID, and commits the artifacts. Adding, removing, or renaming routes inside a domain is handled the same way.
12+
13+
## How sync works (`scripts/sync.ts`)
14+
15+
1. **Discover.** Fetch the combined spec, take every distinct first path segment, keep the ones that serve their own per-domain spec (a 200 at `/api/v2/{slug}/openapi.json`). App utility routes return 401 and drop out, so there is no exclusion list to maintain.
16+
2. **Diff.** Compare the canonical `{ paths, components }` of each live spec against the vendored baseline in `specs/{slug}.json`. Unchanged, already published domains are skipped. No Postman write happens unless the spec changed.
17+
3. **Build.** Rewrite the spec server to the absolute domain base so request URLs resolve, convert with `openapi-to-postmanv2`, then stamp a `roxySlug` variable (stable provenance marker, survives title renames) and an empty `apiKey` so a forked collection is self contained.
18+
4. **Publish.** Resolve the existing collection UID from the cache, then from the live workspace by name. PUT when it exists, POST to create when it does not, and capture the new UID.
19+
5. **Persist.** Write `specs/{slug}.json`, `collections/{slug}.json`, and `collections.json`. The workflow commits them so the next diff has a current baseline.
20+
21+
## Commands
22+
23+
```bash
24+
bun install
25+
bun run sync --dry-run # discover, diff, build, write files. No Postman writes. No key needed.
26+
bun run sync # live. Requires POSTMAN_API_KEY.
27+
bun run sync --force # rebuild and publish every domain regardless of diff.
28+
bun run sync --prune # also delete collections for domains no longer served. Off by default.
29+
bun typecheck
30+
bun run check # biome lint and format
31+
```
32+
33+
## Flags and safety
34+
35+
- `--dry-run` is what CI runs. It proves discovery and conversion work without touching Postman.
36+
- A removed domain is logged, not deleted, unless `--prune` is passed. This prevents a transient API outage from wiping the workspace.
37+
- Spec fetches send `Cache-Control: no-cache` so the diff baseline reflects the freshest origin spec.
38+
39+
## Secrets and config
40+
41+
- `POSTMAN_API_KEY` (repo secret) is the only secret. It is needed for live runs only.
42+
- The workspace ID is non secret and lives in `scripts/sync.ts`.
43+
44+
## Automation
45+
46+
`.github/workflows/sync.yml` runs daily at 06:00 UTC, on manual dispatch, and on a `repository_dispatch` of type `openapi-updated`. It runs the live sync and commits any regenerated artifacts. `.github/workflows/ci.yml` runs lint, typecheck, and a dry run on every PR.

‎CITATION.cff‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
cff-version: 1.2.0
2+
message: "If you use this software, please cite it as below."
3+
title: "RoxyAPI Postman Collections"
4+
abstract: "Public Postman collections for the RoxyAPI catalog, auto-generated and kept in sync from the live OpenAPI specs. One workspace, one API key, every spiritual intelligence domain."
5+
authors:
6+
- name: "RoxyAPI"
7+
url: "https://github.com/RoxyAPI/postman-collections"
8+
repository-code: "https://github.com/RoxyAPI/postman-collections"
9+
license: MIT
10+
type: software
11+
keywords:
12+
- postman
13+
- openapi
14+
- api-collection
15+
- astrology-api
16+
- vedic-astrology-api
17+
- tarot-api
18+
- numerology-api

‎LICENSE‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (c) 2026 RoxyAPI
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

‎README.md‎

Lines changed: 64 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,64 @@
1+
# RoxyAPI Postman Collections
2+
3+
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](./LICENSE)
4+
[![Postman workspace](https://img.shields.io/badge/Postman-public%20workspace-orange.svg)](https://www.postman.com/roxylabs-7113570/roxyapi)
5+
[![Docs](https://img.shields.io/badge/docs-roxyapi.com-blue.svg)](https://roxyapi.com/docs/guides/postman)
6+
7+
Ready to run Postman collections for the full RoxyAPI catalog: Western and Vedic astrology, tarot, numerology, I Ching, biorhythm, dreams, crystals, angel numbers, Human Design, forecast, and location. One workspace, one API key, every domain. Remote MCP, typed SDKs, and drop in UI components live alongside at [roxyapi.com](https://roxyapi.com).
8+
9+
Every collection is generated straight from the live OpenAPI specs and kept in sync automatically. When an endpoint is added, changed, or a whole new domain ships, the collections here follow on the next scheduled run. Nothing in this repo is maintained by hand.
10+
11+
## Use it
12+
13+
Open the public workspace and fork any collection into your own:
14+
15+
[**Explore the RoxyAPI workspace on Postman**](https://www.postman.com/roxylabs-7113570/roxyapi)
16+
17+
Each forked collection carries its own `baseUrl` and an `apiKey` variable. Set `apiKey` to your key (from [your account](https://roxyapi.com/account)) and every request is authenticated through the `X-API-Key` header. That is the only setup.
18+
19+
Prefer Bruno or Insomnia? Both import RoxyAPI directly from a spec URL, no download needed:
20+
21+
```
22+
https://roxyapi.com/api/v2/{domain}/openapi.json
23+
```
24+
25+
for a single domain, or the combined spec:
26+
27+
```
28+
https://roxyapi.com/api/v2/openapi.json
29+
```
30+
31+
## What is in here
32+
33+
| Path | Contents |
34+
|---|---|
35+
| `collections/` | Generated Postman v2.1 collection per domain. Browse or import directly. |
36+
| `specs/` | The OpenAPI spec each collection was built from. The diff baseline for the next sync. |
37+
| `collections.json` | Domain to Postman UID map, written automatically by the sync. |
38+
| `scripts/sync.ts` | The autopilot: discover domains, diff, regenerate, publish. |
39+
40+
The set of domains is discovered from the live API, so it always matches what is actually shipped. To see the current list, browse [`collections/`](./collections) or the [products page](https://roxyapi.com/products).
41+
42+
## Authentication
43+
44+
| Variable | Where to set | Value |
45+
|---|---|---|
46+
| `apiKey` | Collection or environment variable | Your RoxyAPI key |
47+
| `baseUrl` | Preset per collection | `https://roxyapi.com/api/v2/{domain}` |
48+
49+
All requests inherit collection level API key auth. The key travels in the `X-API-Key` header. The same key works across every domain.
50+
51+
## Verified accuracy
52+
53+
The astrology and Vedic domains are verified against NASA JPL Horizons. See the public [methodology](https://roxyapi.com/methodology) and the gold standard test suite write up.
54+
55+
## Links
56+
57+
- API docs and reference: [roxyapi.com/docs](https://roxyapi.com/docs)
58+
- Postman guide: [roxyapi.com/docs/guides/postman](https://roxyapi.com/docs/guides/postman)
59+
- TypeScript, Python, and PHP SDKs: [roxyapi.com/docs/sdk](https://roxyapi.com/docs/sdk)
60+
- Remote MCP and starters: [roxyapi.com/starters](https://roxyapi.com/starters)
61+
62+
## License
63+
64+
MIT. See [LICENSE](./LICENSE).

0 commit comments

Comments
 (0)