@inklok/api-spec 7.2.0 → 7.2.1

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 (3) hide show
  1. package/README.md +101 -90
  2. package/openapi.yaml +1 -1
  3. package/package.json +12 -7
package/README.md CHANGED
@@ -1,134 +1,145 @@
1
- # OpenAPI Specification — OpaqueInk Core API
1
+ # Inklok API Specification
2
2
 
3
- This directory contains the **canonical OpenAPI v3 specification** for OpaqueInk core Lambda endpoints.
3
+ Canonical OpenAPI v3 specification for the Inklok public API.
4
4
 
5
- ## Ownership
5
+ This package contains the API contract used by Inklok developer tools, SDKs, and integrations. It defines available endpoints, request and response schemas, authentication requirements, and shared API components.
6
6
 
7
- **This specification is owned by `opaqueink_infra` and is the single source of truth for API contracts.**
7
+ ## Installation
8
8
 
9
- - API Gateway routes are generated from this specification
10
- - Terraform uses this spec to configure API Gateway integrations
11
- - `opaqueink_core` consumes this spec but does not own it
12
- - All API changes must be made here first, then propagated to implementations
9
+ Install the specification package from npm:
13
10
 
14
- ## API URL Configuration
11
+ ```bash
12
+ npm install @inklok/api-spec
13
+ ```
14
+
15
+ ## Usage
16
+
17
+ The specification can be used to:
18
+
19
+ - Generate API clients
20
+ - Generate strongly typed models
21
+ - Validate requests and responses
22
+ - Build custom integrations
23
+ - Keep integrations aligned with the Inklok API contract
15
24
 
16
- **⚠️ IMPORTANT: The API server URL is configured in `openapi.yaml` under the `servers` section.**
25
+ Example:
17
26
 
18
- To update the API Gateway URL, edit the `servers` section in `openapi.yaml`:
27
+ ```js
28
+ import fs from "node:fs";
19
29
 
20
- ```yaml
21
- servers:
22
- - url: https://YOUR-API-GATEWAY-URL/prod
23
- description: Production API Gateway
30
+ const openapi = fs.readFileSync(
31
+ "node_modules/@inklok/api-spec/openapi.yaml",
32
+ "utf8"
33
+ );
34
+
35
+ console.log(openapi);
24
36
  ```
25
37
 
26
- The Scalar documentation build script automatically reads this URL from the OpenAPI spec, so updating it here will update the documentation as well.
38
+ ## API Documentation
27
39
 
28
- **Current API URL:** `https://4rh4k08rih.execute-api.us-east-2.amazonaws.com/prod`
40
+ The interactive API reference is available at:
29
41
 
30
- ## Structure
42
+ https://docs.inklok.com/docs/api-reference
31
43
 
32
- - **`openapi.yaml`** - Complete OpenAPI v3 specification with inline component references
33
- - **`components/`** - Modular component definitions (for maintainability, but consolidated into openapi.yaml for API Gateway)
34
- - `schemas.yaml` - Data model schemas
35
- - `responses.yaml` - Standard response definitions
36
- - `security.yaml` - Security scheme definitions
37
- - **`package.json`** - Node.js dependencies for validation and deployment
44
+ The API reference includes:
38
45
 
39
- ## Building and Validation
46
+ - Endpoint documentation
47
+ - Authentication requirements
48
+ - Request and response schemas
49
+ - Example requests and responses
50
+ - Interactive API exploration
40
51
 
41
- ### Install Dependencies
52
+ ## API Endpoint
42
53
 
43
- ```bash
44
- cd api
45
- npm install
46
- ```
54
+ The production Inklok API endpoint is:
47
55
 
48
- ### Validate the Specification
56
+ https://api.inklok.com
49
57
 
50
- **Using basic validation:**
51
- ```bash
52
- npm install
53
- npm run validate-basic
54
- # or directly:
55
- node validate-basic.js
56
- ```
58
+ SDK clients and integrations should use this as the API base URL.
57
59
 
58
- **Using the validation script** (includes multiple fallbacks):
59
- ```bash
60
- chmod +x validate.sh
61
- ./validate.sh
62
- ```
60
+ ## Package Contents
63
61
 
64
- ### Build Documentation
62
+ This package contains:
65
63
 
66
- ```bash
67
- npm run build-docs
64
+ ```text
65
+ openapi.yaml
66
+ components/
67
+ schemas.yaml
68
+ responses.yaml
69
+ security.yaml
70
+ package.json
68
71
  ```
69
72
 
70
- This builds the Scalar API documentation with interactive "Try-It-Out" functionality.
73
+ ## Specification Details
71
74
 
72
- ### Deploy Documentation
75
+ This package follows the OpenAPI specification format.
73
76
 
74
- ```bash
75
- export S3_BUCKET_NAME="your-bucket-name"
76
- export CLOUDFRONT_DISTRIBUTION_ID="your-distribution-id"
77
- npm run deploy-docs
78
- ```
77
+ It defines:
78
+
79
+ - API paths and operations
80
+ - Request parameters
81
+ - Request bodies
82
+ - Response schemas
83
+ - Authentication schemes
84
+ - Shared response definitions
79
85
 
80
- This builds and deploys the documentation to S3/CloudFront.
86
+ ## Authentication
81
87
 
82
- ## Integration with API Gateway
88
+ The Inklok API uses authenticated requests.
83
89
 
84
- The `openapi.yaml` file uses `x-amazon-apigateway-*` extensions to define:
90
+ Supported authentication methods include:
85
91
 
86
- - Lambda integrations (`x-amazon-apigateway-integration`)
87
- - Authentication configuration
88
- - Request/response mappings
89
- - CORS behavior
92
+ - User access tokens
93
+ - Inklok API keys
90
94
 
91
- Terraform in `../api_gateway/` imports this specification to configure API Gateway.
95
+ See the API reference for authentication details and examples.
92
96
 
93
97
  ## API Versioning
94
98
 
95
- **⚠️ HARD REQUIREMENT: All new endpoints MUST be versioned using `/v1/` path prefix.**
99
+ The Inklok API uses versioned endpoints.
100
+
101
+ New API capabilities are introduced using version prefixes:
102
+
103
+ ```text
104
+ /v1/agreements
105
+ /v1/documents
106
+ ```
107
+
108
+ Applications should use the versioned API paths documented in the API reference.
109
+
110
+ ## Validation
111
+
112
+ To validate the specification locally:
96
113
 
97
- See [API_VERSIONING.md](API_VERSIONING.md) for the complete versioning strategy and requirements.
114
+ ```bash
115
+ npm install
116
+ npm run validate-basic
117
+ ```
98
118
 
99
- **Quick Reference:**
100
- - ✅ New endpoint: `/v1/orgs/{orgId}/members`
101
- - ❌ Missing version: `/orgs/{orgId}/members` (not allowed for new endpoints)
119
+ ## Consuming Updates
102
120
 
103
- ## Adding New Endpoints
121
+ The package is published as:
104
122
 
105
- 1. **⚠️ Ensure path includes `/v1/` prefix** (see [API_VERSIONING.md](API_VERSIONING.md))
106
- 2. **Add the path definition** to `openapi.yaml` under `paths:`
107
- 3. **Add the Lambda integration** using `x-amazon-apigateway-integration` extension
108
- 4. **Add schemas** to `components/schemas` if needed
109
- 5. **Add responses** using component references (e.g., `$ref: '#/components/responses/Unauthorized'`)
110
- 6. **Run validation**: `npm run validate-basic`
111
- 7. **Update Terraform** in `../api_gateway/` to reference the new Lambda function
123
+ ```text
124
+ @inklok/api-spec
125
+ ```
126
+
127
+ Install:
112
128
 
113
- ## Editing Guidelines
129
+ ```bash
130
+ npm install @inklok/api-spec
131
+ ```
114
132
 
115
- - **⚠️ Versioning**: All new endpoints MUST use `/v1/` path prefix (see [API_VERSIONING.md](API_VERSIONING.md))
116
- - **Operation IDs** must be unique and descriptive (use kebab-case)
117
- - **All endpoints** require Bearer JWT authentication (defined globally)
118
- - **Error responses** should use component references from `components/responses`
119
- - **Schemas** should be defined in `components/schemas` and referenced
120
- - **Tags** should be used consistently to group related operations
133
+ New versions are released as the Inklok API evolves.
121
134
 
122
- ## Publishing to npm
135
+ ## Related Resources
123
136
 
124
- This package is published to the public npm registry as `@inklok/api-spec` so `opaqueink_core` and other repos can consume it for codegen and type generation.
137
+ API Reference:
138
+ https://docs.inklok.com/docs/api-reference
125
139
 
126
- - **Manual publish:** See [PUBLISH.md](PUBLISH.md) for setup and `npm publish` instructions
127
- - **CI publish:** Create a GitHub Release to trigger `.github/workflows/publish-api-spec.yml`
128
- - **Consuming:** `npm install @inklok/api-spec`
140
+ Inklok:
141
+ https://inklok.com
129
142
 
130
- ## Reference
143
+ ## License
131
144
 
132
- - [OpenAPI 3.0 Specification](https://swagger.io/specification/)
133
- - [API Gateway OpenAPI Extensions](https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-swagger-extensions.html)
134
- - [Scalar API Reference](https://github.com/scalar/scalar)
145
+ See package metadata for licensing information.
package/openapi.yaml CHANGED
@@ -8,7 +8,7 @@ info:
8
8
  Authenticate using an API key or bearer token, then use the resources below to manage
9
9
  templates, agreements, documents, and signing. For your first integration, start with
10
10
  the Quick Start guide.
11
- version: "7.2.0"
11
+ version: "7.2.1"
12
12
  contact:
13
13
  name: Inklok API Support
14
14
  email: support@inklok.com
package/package.json CHANGED
@@ -1,8 +1,18 @@
1
1
  {
2
2
  "name": "@inklok/api-spec",
3
- "version": "7.2.0",
4
- "description": "OpenAPI specification for OpaqueInk Core API (owned by opaqueink_infra)",
3
+ "version": "7.2.1",
4
+ "description": "Canonical OpenAPI specification for the Inklok public API.",
5
5
  "main": "openapi.yaml",
6
+ "license": "MIT",
7
+ "keywords": [
8
+ "inklok",
9
+ "api",
10
+ "openapi",
11
+ "sdk",
12
+ "typescript",
13
+ "integration",
14
+ "developer"
15
+ ],
6
16
  "files": [
7
17
  "openapi.yaml",
8
18
  "components/",
@@ -22,11 +32,6 @@
22
32
  "engines": {
23
33
  "node": ">=18.0.0"
24
34
  },
25
- "repository": {
26
- "type": "git",
27
- "url": "https://github.com/ryan-m-erickson/opaqueink_infra.git",
28
- "directory": "api"
29
- },
30
35
  "publishConfig": {
31
36
  "registry": "https://registry.npmjs.org",
32
37
  "access": "public"