@apifreaks/openapi-specs 0.3.1 → 0.3.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (17) hide show
  1. package/README.md +75 -98
  2. package/dist/index.cjs +6540 -942
  3. package/dist/index.d.cts +13 -5
  4. package/dist/index.d.ts +13 -5
  5. package/dist/index.js +7169 -1574
  6. package/dist/specs/pdf/{bulk-pdf-generator.yaml → pdf-generator-bulk.yaml} +2 -2
  7. package/dist/specs/pdf/pdf-generator.yaml +2 -2
  8. package/package.json +1 -1
  9. package/specs/README.md +259 -0
  10. package/specs/pdf/{bulk-pdf-generator.json → pdf-generator-bulk.json} +2 -2
  11. package/specs/pdf/pdf-generator.json +2 -2
  12. /package/dist/specs/pdf/{pdf-split-pages.yaml → split-pdf.yaml} +0 -0
  13. /package/dist/specs/{phone-validation → phone-number-validation}/bulk-phone-number-validation.yaml +0 -0
  14. /package/dist/specs/{phone-validation/phone-number-validation.yaml → phone-number-validation/phone-validation.yaml} +0 -0
  15. /package/specs/pdf/{pdf-split-pages.json → split-pdf.json} +0 -0
  16. /package/specs/{phone-validation → phone-number-validation}/bulk-phone-number-validation.json +0 -0
  17. /package/specs/{phone-validation/phone-number-validation.json → phone-number-validation/phone-validation.json} +0 -0
package/README.md CHANGED
@@ -1,6 +1,11 @@
1
1
  # @apifreaks/openapi-specs
2
2
 
3
- OpenAPI 3.1 specifications for all [APIFreaks](https://apifreaks.com) API products. Ships 104 production specs across 20 categories as typed JSON, importable as ESM, CJS, or raw JSON.
3
+ [![npm](https://img.shields.io/npm/v/@apifreaks/openapi-specs.svg)](https://www.npmjs.com/package/@apifreaks/openapi-specs)
4
+ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
5
+
6
+ npm package and source repo for the public [OpenAPI 3.1](https://spec.openapis.org/oas/v3.1.1.html) specifications of [APIFreaks](https://apifreaks.com) products.
7
+
8
+ The specs (catalog, authentication, and how to open them in Swagger, Postman, or a code generator) are in **[specs/README.md](specs/README.md)**. This README is the package: install, the typed lookup API, and how the repo is built.
4
9
 
5
10
  ## Install
6
11
 
@@ -8,148 +13,120 @@ OpenAPI 3.1 specifications for all [APIFreaks](https://apifreaks.com) API produc
8
13
  npm install @apifreaks/openapi-specs
9
14
  ```
10
15
 
16
+ Node.js 18 or later. ESM and CommonJS are both supported.
17
+
11
18
  ## Usage
12
19
 
13
- ### Programmatic API
20
+ Importing anything from `@apifreaks/openapi-specs` (the package entry) loads every spec. Use that when you need to list or look up specs at runtime. For a single product, import the JSON file (see below) so you do not go through that entry.
21
+
22
+ ### Lookup
14
23
 
15
24
  ```ts
16
25
  import {
17
- getSpec,
26
+ getSpecJson,
27
+ getSpecYaml,
18
28
  getSpecsByCategory,
19
- SPEC_SLUGS,
20
- SPEC_CATEGORIES,
21
- SPECS_BY_CATEGORY,
29
+ SpecSlug,
30
+ SpecCategory,
22
31
  } from "@apifreaks/openapi-specs";
23
32
 
24
- // Get a single spec by slug
25
- const spec = getSpec("ip-locator");
26
-
27
- // Get all slugs in a category
28
- const ipSlugs = getSpecsByCategory("ip-intelligence");
33
+ const spec = getSpecJson(SpecSlug.IP_LOCATOR);
34
+ const yaml = getSpecYaml(SpecSlug.IP_LOCATOR);
35
+ const ipSlugs = getSpecsByCategory(SpecCategory.IP_INTELLIGENCE);
36
+ ```
29
37
 
30
- // All available slugs
31
- console.log(SPEC_SLUGS); // ['ip-locator', 'dns-lookup', ...]
38
+ `SpecSlug` and `SpecCategory` are generated from `specs/`. If you write `SpecSlug.IP_LOCATOR` and that file is later renamed or removed, TypeScript fails at compile time. Raw strings (`getSpecJson("ip-locator")`) still typecheck; unknown slugs return `undefined` at runtime. Unknown categories return `[]`.
32
39
 
33
- // All categories
34
- console.log(SPEC_CATEGORIES); // ['currency', 'dns', 'ip-intelligence', ...]
40
+ `getSpec` is a deprecated alias for `getSpecJson` and will be removed in the next major version.
35
41
 
36
- // All slugs grouped by category
37
- console.log(SPECS_BY_CATEGORY);
38
- ```
42
+ ### Single spec
39
43
 
40
- ### Direct JSON import (tree-shakable)
44
+ JSON is published from `specs/`. TypeScript JSON imports need `"resolveJsonModule": true`.
41
45
 
42
46
  ```ts
43
47
  import ipLocator from "@apifreaks/openapi-specs/specs/ip-intelligence/ip-locator.json";
44
48
  ```
45
49
 
50
+ YAML copies are also generated at build time into `dist/specs/` (not in the GitHub `specs/` folder) and published as files, but the YAML text is also embedded in the manifest — reading it through `getSpecYaml(slug)` at runtime, rather than importing the `.yaml` file, works from any module system (Node can't `import` `.yaml`) and needs no filesystem access.
51
+
46
52
  ### CommonJS
47
53
 
48
54
  ```js
49
- const { getSpec, SPEC_SLUGS } = require("@apifreaks/openapi-specs");
55
+ const { getSpecJson, getSpecYaml, SpecSlug } = require("@apifreaks/openapi-specs");
50
56
  ```
51
57
 
52
- ## API
58
+ ## Exports
53
59
 
54
- | Export | Type | Description |
55
- | ------------------------------ | -------------------------------------- | --------------------------------------------------- |
56
- | `getSpec(slug)` | `(string) => OpenAPISpec \| undefined` | Returns the full spec object for a given slug |
57
- | `getSpecsByCategory(category)` | `(string) => string[]` | Returns all slugs in a category, or `[]` if unknown |
58
- | `SPEC_SLUGS` | `string[]` | All 104 spec slugs |
59
- | `SPEC_CATEGORIES` | `string[]` | All 20 category names |
60
- | `SPECS` | `Record<string, OpenAPISpec>` | Full spec objects keyed by slug |
61
- | `SPECS_BY_CATEGORY` | `Record<string, string[]>` | Slugs grouped by category |
60
+ Importing any of these from `@apifreaks/openapi-specs` loads every spec.
62
61
 
63
- ### Types
62
+ | Export | Type | Description |
63
+ | ------ | ---- | ----------- |
64
+ | `getSpecJson(slug)` | `(string) => OpenAPISpec \| undefined` | Spec object for a slug |
65
+ | `getSpecYaml(slug)` | `(string) => string \| undefined` | Pre-rendered YAML text for a slug |
66
+ | `getSpec(slug)` | `(string) => OpenAPISpec \| undefined` | **Deprecated.** Alias for `getSpecJson`, removed in the next major version |
67
+ | `getSpecsByCategory(category)` | `(string) => string[]` | Slugs in a category, or `[]` |
68
+ | `SpecSlug` | `{ IP_LOCATOR: "ip-locator", … }` | Enumerated slugs |
69
+ | `SpecCategory` | `{ IP_INTELLIGENCE: "ip-intelligence", … }` | Enumerated categories |
70
+ | `SPEC_SLUGS` | `string[]` | All slugs |
71
+ | `SPEC_CATEGORIES` | `string[]` | All category names |
72
+ | `SPECS` | `Record<string, OpenAPISpec>` | Spec objects keyed by slug |
73
+ | `SPECS_YAML` | `Record<string, string>` | Pre-rendered YAML text keyed by slug |
74
+ | `SPECS_BY_CATEGORY` | `Record<string, string[]>` | Slugs grouped by category |
64
75
 
65
76
  ```ts
66
- import type { OpenAPISpec } from "@apifreaks/openapi-specs";
67
-
68
- // OpenAPISpec has: openapi, info, servers?, paths?, components?, [key: string]
77
+ import type {
78
+ OpenAPISpec,
79
+ SpecSlugValue,
80
+ SpecCategoryValue,
81
+ } from "@apifreaks/openapi-specs";
69
82
  ```
70
83
 
71
- ## Categories
72
-
73
- | Category | Count | Description |
74
- | ------------------ | ----- | ------------------------------------------------------- |
75
- | `billing` | 1 | Usage and credits |
76
- | `commodity` | 5 | Commodity prices, symbols, time series |
77
- | `currency` | 10 | Exchange rates, conversion, historical data |
78
- | `dns` | 4 | DNS lookup, reverse DNS, history |
79
- | `domain` | 4 | Domain search, checker, subdomain lookup |
80
- | `email-validation` | 2 | Email verification and bulk validation |
81
- | `financial` | 8 | VAT rates, IBAN/SWIFT validation |
82
- | `geocoding` | 2 | Forward and reverse geocoding |
83
- | `geography` | 10 | Countries, cities, regions, flags, administrative units |
84
- | `ip-intelligence` | 4 | IP geolocation, threat intelligence, bulk lookup |
85
- | `pdf` | 19 | PDF manipulation, conversion, encryption |
86
- | `phone-validation` | 2 | Phone number validation |
87
- | `scraper` | 1 | Web scraping |
88
- | `screenshot` | 2 | Website screenshots |
89
- | `ssl` | 2 | SSL certificate lookup |
90
- | `timezone` | 2 | Timezone lookup and conversion |
91
- | `user-agent` | 2 | User-agent parsing |
92
- | `weather` | 9 | Current, forecast, historical, marine weather, astronomy |
93
- | `whois` | 6 | WHOIS lookup, ASN, reverse WHOIS |
94
- | `zip-code` | 7 | Zip code lookup, distance, radius search |
84
+ `OpenAPISpec` is a typed envelope (`openapi`, `info`, `paths`, …), not a full OpenAPI 3.1 schema.
95
85
 
96
86
  ## Development
97
87
 
88
+ ```
89
+ specs/ # OpenAPI JSON. See specs/README.md
90
+ src/
91
+ index.ts # Public API
92
+ types.ts # OpenAPISpec
93
+ manifest.ts # AUTO-GENERATED. Do not edit.
94
+ scripts/
95
+ generate-manifest.ts # Walks specs/, writes src/manifest.ts (embeds JSON + YAML)
96
+ generate-yaml.ts # JSON → dist/specs/**/*.yaml (published files)
97
+ yaml.ts # Shared JSON->YAML dump used by both scripts
98
+ test/
99
+ validate.test.ts # JSON well-formedness; YAML round-trip after build
100
+ ```
101
+
98
102
  ```bash
99
- # Install deps
100
103
  npm install
101
-
102
- # Generate manifest (auto-discovers specs/ and writes src/manifest.ts)
103
- npm run generate
104
-
105
- # Build (generate + tsup)
106
- npm run build
107
-
108
- # Typecheck
104
+ npm run generate # regenerate src/manifest.ts from specs/
105
+ npm run build # generate + bundle + YAML
109
106
  npm run typecheck
110
-
111
- # Test
112
107
  npm test
113
108
  ```
114
109
 
115
- ### Project structure
110
+ `src/manifest.ts` is produced by `npm run generate`. It imports every spec and builds `SPECS`, `SPECS_YAML`, `SPEC_SLUGS`, `SpecSlug`, and `SpecCategory`.
116
111
 
117
- ```
118
- specs/ # OpenAPI 3.1 JSON files, organized by category
119
- currency/
120
- currency-converter.json
121
- ip-intelligence/
122
- ip-locator.json
123
- ...
124
- src/
125
- index.ts # Public API
126
- manifest.ts # AUTO-GENERATED — do not edit manually
127
- types.ts # OpenAPISpec type definition
128
- scripts/
129
- generate-manifest.ts # Reads specs/, writes src/manifest.ts
130
- test/
131
- validate.test.ts # Validates every spec is valid JSON + well-formed OpenAPI
132
- ```
133
-
134
- ### Adding a new spec
112
+ ### Adding a spec
135
113
 
136
- 1. Add the `.json` file under the appropriate category in `specs/`
137
- 2. Run `npm run generate` to regenerate `src/manifest.ts`
138
- 3. Run `npm test` to validate
139
- 4. Run `npm run build` to rebuild the package
114
+ 1. Add a complete OpenAPI 3.1 document at `specs/<category>/<slug>.json`. Use the same security schemes as the existing files: header `X-apiKey` and query `apiKey`.
115
+ 2. Run `npm run generate`. Do not edit `src/manifest.ts` by hand.
116
+ 3. Run `npm test`, then `npm run build`.
140
117
 
141
- `src/manifest.ts` is auto-generated and must not be edited by hand.
118
+ ## Maintainers
142
119
 
143
- ## Publishing
120
+ `prepublishOnly` runs the build. The published tarball includes `dist/`, `specs/`, `package.json`, README, and LICENSE.
144
121
 
145
- The package is built automatically before publish via `prepublishOnly`.
122
+ Pushing a tag matching `v*` publishes to npm via GitHub Actions. The bump scripts **test, commit a version, tag, and push**; they will trigger that publish:
146
123
 
147
124
  ```bash
148
- npm publish --access public
125
+ npm run bump:patch
126
+ npm run bump:minor
127
+ npm run bump:major
149
128
  ```
150
129
 
151
- The published package includes only `dist/` and `specs/`. Tests, scripts, and build configs are excluded.
152
-
153
130
  ## License
154
131
 
155
- MIT
132
+ [MIT](LICENSE)