@voidhash/api-spec 0.0.1-alpha.1-canary.2.1.223955

package/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Voidhash s.r.o.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,43 @@
+# @voidhash/api-spec
+
+`@voidhash/api-spec` contains the shared Voidhash API contracts (routes, schemas, auth headers, and API error types).
+
+## Installation
+
+Install stable:
+
+```bash
+pnpm add @voidhash/api-spec@latest
+```
+
+Install a specific version:
+
+```bash
+pnpm add @voidhash/api-spec@0.0.1-alpha.1
+```
+
+Install latest canary:
+
+```bash
+pnpm add @voidhash/api-spec@canary
+```
+
+## Runtime Expectations
+
+- ESM package (`"type": "module"`).
+- Exports TypeScript source files from `src`.
+- Consumers should compile TS dependencies in their build pipeline.
+- Peer dependencies are required from the consuming app:
+  - `effect`
+  - `@effect/platform`
+
+## Release Channels
+
+- `latest`: stable releases published from `main`.
+- `canary`: preview builds published from pushes to `preview`.
+
+Recommended flow:
+
+1. Push `api-spec` changes to `preview` to publish a canary build.
+2. Validate in `voidhash-mono` against `@voidhash/api-spec@canary` (or the exact canary version).
+3. Merge to `main` and publish `latest`.

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@voidhash/api-spec",
+  "version": "0.0.1-alpha.1-canary.2.1.0223955",
+  "private": false,
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/voidhashcom/voidhash",
+    "directory": "packages/api-spec"
+  },
+  "files": [
+    "src",
+    "LICENSE.md",
+    "README.md",
+    "package.json"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts",
+    "./errors": "./src/errors/index.ts"
+  },
+  "scripts": {
+    "typecheck": "tsgo --noEmit"
+  },
+  "dependencies": {},
+  "devDependencies": {
+    "@voidhash/tsconfig": "workspace:*",
+    "typescript": "5.6.3"
+  },
+  "peerDependencies": {
+    "@effect/platform": "catalog:",
+    "effect": "catalog:"
+  }
+}

package/src/api.ts

@@ -0,0 +1,420 @@
+import { HttpApi, HttpApiEndpoint, HttpApiGroup } from "@effect/platform";
+import { Schema } from "effect";
+
+import {
+  ActionForbiddenError,
+  ApiKeyNotFoundError,
+  ApiKeyServiceError,
+  AuthenticationError,
+  ChangesetDeploymentServiceError,
+  CustomerInvalidAnonymousIdError,
+  CustomerNotFoundError,
+  CustomerServiceError,
+  OrganizationServiceError,
+  PaymentProviderConfigurationServiceError,
+  PaymentProviderProductServiceError,
+  PaywallLocationServiceError,
+  PerkServiceError,
+  ProductPerkServiceError,
+  ProductPerkValidationError,
+  ProductServiceError,
+  ProjectServiceError,
+  SdkCustomerAlreadyIdentifiedError,
+  SdkCustomerNotFoundError,
+  SdkServiceError,
+  SdkValidationError,
+  UserServiceError,
+  WebhookDeliveryNotFoundError,
+  WebhookEndpointNotFoundError,
+  WebhookServiceError,
+  WebhookValidationError,
+} from "./errors";
+import { AuthMiddleware } from "./middlewares";
+import {
+  ApiKey,
+  ApiKeyIdParam,
+  ApiKeyWithRawKey,
+  AppUserIdParam,
+  CreateCustomerBody,
+  CreateOrganizationBody,
+  CreateProjectBody,
+  CreateSecretKeyBody,
+  CreateWebhookEndpointBody,
+  Customer,
+  CustomerIdParam,
+  DeployChangesetBody,
+  DeployChangesetResponse,
+  Organization,
+  OrganizationIdParam,
+  PaymentProviderConfiguration,
+  PaymentProviderProduct,
+  PaywallLocation,
+  Perk,
+  Product,
+  ProductIdParam,
+  ProductPerk,
+  Project,
+  EvaluateFeatureFlagsBody,
+  SdkCustomer,
+  SdkFeatureFlagsResponse,
+  SdkHeaders,
+  SdkIdentifyBody,
+  SdkResolvePaywallBody,
+  SdkResolvedPaywall,
+  SdkSyncCustomerAttributesBody,
+  SdkSyncTransactionBody,
+  SdkSyncTransactionResponse,
+  Session,
+  UpdateWebhookEndpointBody,
+  User,
+  WebhookDelivery,
+  WebhookDeliveryIdParam,
+  WebhookDeliveryWithAttempts,
+  WebhookEndpoint,
+  WebhookEndpointIdParam,
+} from "./schema";
+
+export const VoidhashV1Api = HttpApi.make("VoidhashV1Api")
+  .add(
+    HttpApiGroup.make("auth")
+      .add(
+        HttpApiEndpoint.get("session")`/session`
+          .addSuccess(Session)
+          .addError(ActionForbiddenError)
+          .middleware(AuthMiddleware)
+      )
+      .prefix("/auth")
+  )
+  .add(
+    HttpApiGroup.make("api_keys")
+      .add(
+        HttpApiEndpoint.post("createSecretKey")`/`
+          .addSuccess(ApiKeyWithRawKey)
+          .setPayload(CreateSecretKeyBody)
+          .addError(ApiKeyServiceError)
+          .addError(ActionForbiddenError)
+      )
+      .add(
+        HttpApiEndpoint.get("listApiKeys")`/`
+          .addSuccess(Schema.Array(ApiKey))
+          .addError(ApiKeyServiceError)
+          .addError(ActionForbiddenError)
+      )
+      .add(
+        HttpApiEndpoint.get("getApiKeyById")`/${ApiKeyIdParam}`
+          .addSuccess(ApiKey)
+          .addError(ApiKeyServiceError)
+          .addError(ApiKeyNotFoundError)
+          .addError(ActionForbiddenError)
+      )
+      .add(
+        HttpApiEndpoint.post("rotateSecretKey")`/${ApiKeyIdParam}/rotate`
+          .addSuccess(ApiKeyWithRawKey)
+          .addError(ApiKeyServiceError)
+          .addError(ApiKeyNotFoundError)
+          .addError(ActionForbiddenError)
+      )
+      .add(
+        HttpApiEndpoint.del("deleteApiKey")`/${ApiKeyIdParam}`
+          .addError(ApiKeyServiceError)
+          .addError(ApiKeyNotFoundError)
+          .addError(ActionForbiddenError)
+      )
+      .middleware(AuthMiddleware)
+      .prefix("/api-keys")
+  )
+  .add(
+    HttpApiGroup.make("customers")
+      .add(
+        HttpApiEndpoint.post("createCustomer")`/`
+          .setPayload(CreateCustomerBody)
+          .addSuccess(Customer)
+          .addError(ActionForbiddenError)
+          .addError(CustomerInvalidAnonymousIdError)
+          .addError(CustomerServiceError)
+      )
+      .add(
+        HttpApiEndpoint.get("listCustomers")`/`
+          .addSuccess(Schema.Array(Customer))
+          .addError(ActionForbiddenError)
+          .addError(CustomerServiceError)
+      )
+      .add(
+        HttpApiEndpoint.get("getCustomerById")`/${CustomerIdParam}`
+          .addSuccess(Customer)
+          .addError(ActionForbiddenError)
+          .addError(CustomerNotFoundError)
+          .addError(CustomerServiceError)
+      )
+      .add(
+        HttpApiEndpoint.get("byAppUserId")`/by-app-user-id/${AppUserIdParam}`
+          .addSuccess(Customer)
+          .addError(ActionForbiddenError)
+          .addError(CustomerNotFoundError)
+          .addError(CustomerServiceError)
+      )
+      .middleware(AuthMiddleware)
+      .prefix("/customers")
+  )
+  .add(
+    HttpApiGroup.make("organizations")
+      .add(
+        HttpApiEndpoint.post("createOrganization")`/`
+          .setPayload(CreateOrganizationBody)
+          .addSuccess(Organization)
+          .addError(OrganizationServiceError)
+      )
+      .middleware(AuthMiddleware)
+      .prefix("/organizations")
+  )
+  .add(
+    HttpApiGroup.make("perks")
+      .add(
+        HttpApiEndpoint.get("listPerks")`/`
+          .addSuccess(Schema.Array(Perk))
+          .addError(ActionForbiddenError)
+          .addError(PerkServiceError)
+      )
+      .middleware(AuthMiddleware)
+      .prefix("/perks")
+  )
+  .add(
+    HttpApiGroup.make("paywall_locations")
+      .add(
+        HttpApiEndpoint.get("listPaywallLocations")`/`
+          .addSuccess(Schema.Array(PaywallLocation))
+          .addError(ActionForbiddenError)
+          .addError(PaywallLocationServiceError)
+      )
+      .middleware(AuthMiddleware)
+      .prefix("/paywall-locations")
+  )
+  .add(
+    HttpApiGroup.make("projects")
+      .add(
+        HttpApiEndpoint.post("createProject")`/`
+          .setPayload(CreateProjectBody)
+          .addSuccess(Project)
+          .addError(ActionForbiddenError)
+          .addError(AuthenticationError)
+          .addError(ProjectServiceError)
+      )
+      .add(
+        HttpApiEndpoint.get("listProjects")`/${OrganizationIdParam}`
+          .addSuccess(Schema.Array(Project))
+          .addError(ActionForbiddenError)
+          .addError(ProjectServiceError)
+      )
+      .middleware(AuthMiddleware)
+      .prefix("/projects")
+  )
+  .add(
+    HttpApiGroup.make("products")
+      .add(
+        HttpApiEndpoint.get("listProducts")`/`
+          .addSuccess(Schema.Array(Product))
+          .addError(ActionForbiddenError)
+          .addError(ProductServiceError)
+      )
+      .middleware(AuthMiddleware)
+      .prefix("/products")
+  )
+  .add(
+    HttpApiGroup.make("product_perks")
+      .add(
+        HttpApiEndpoint.get(
+          "listProductPerksByProductId"
+        )`/by-product-id/${ProductIdParam}`
+          .addSuccess(Schema.Array(ProductPerk))
+          .addError(ActionForbiddenError)
+          .addError(ProductPerkServiceError)
+          .addError(ProductPerkValidationError)
+      )
+      .middleware(AuthMiddleware)
+      .prefix("/product-perks")
+  )
+  .add(
+    HttpApiGroup.make("sdk")
+      .add(
+        HttpApiEndpoint.get("getCustomer")`/get-customer`
+          .addSuccess(SdkCustomer)
+          .setHeaders(SdkHeaders)
+          .addError(AuthenticationError)
+          .addError(SdkServiceError)
+          .addError(SdkCustomerNotFoundError)
+          .addError(SdkValidationError)
+      )
+      .add(
+        HttpApiEndpoint.post("identify")`/identify`
+          .setPayload(SdkIdentifyBody)
+          .addSuccess(SdkCustomer)
+          .setHeaders(SdkHeaders)
+          .addError(AuthenticationError)
+          .addError(SdkServiceError)
+          .addError(SdkValidationError)
+          .addError(SdkCustomerAlreadyIdentifiedError)
+      )
+      .add(
+        HttpApiEndpoint.post(
+          "syncCustomerAttributes"
+        )`/sync-customer-attributes`
+          .setPayload(SdkSyncCustomerAttributesBody)
+          .addSuccess(SdkCustomer)
+          .setHeaders(SdkHeaders)
+          .addError(AuthenticationError)
+          .addError(SdkServiceError)
+          .addError(SdkValidationError)
+      )
+      .add(
+        HttpApiEndpoint.post("syncTransaction")`/sync-transaction`
+          .setPayload(SdkSyncTransactionBody)
+          .addSuccess(SdkSyncTransactionResponse)
+          .setHeaders(SdkHeaders)
+          .addError(AuthenticationError)
+          .addError(SdkServiceError)
+          .addError(SdkValidationError)
+      )
+      .add(
+        HttpApiEndpoint.post("evaluateFeatureFlags")`/evaluate-flags`
+          .setPayload(EvaluateFeatureFlagsBody)
+          .addSuccess(SdkFeatureFlagsResponse)
+          .setHeaders(SdkHeaders)
+          .addError(AuthenticationError)
+          .addError(SdkServiceError)
+      )
+      .add(
+        HttpApiEndpoint.post("resolvePaywall")`/resolve-paywall`
+          .setPayload(SdkResolvePaywallBody)
+          .addSuccess(Schema.NullOr(SdkResolvedPaywall))
+          .setHeaders(SdkHeaders)
+          .addError(AuthenticationError)
+          .addError(SdkServiceError)
+          .addError(SdkValidationError)
+      )
+      .middleware(AuthMiddleware)
+      .prefix("/sdk")
+  )
+  .add(
+    HttpApiGroup.make("users")
+      .add(
+        HttpApiEndpoint.get("getUser")`/current`
+          .addSuccess(User)
+          .addError(AuthenticationError)
+          .addError(UserServiceError)
+      )
+      .middleware(AuthMiddleware)
+      .prefix("/users")
+  )
+  .add(
+    HttpApiGroup.make("payment_provider_configurations")
+      .add(
+        HttpApiEndpoint.get("listPaymentProviderConfigurations")`/`
+          .addSuccess(Schema.Array(PaymentProviderConfiguration))
+          .addError(ActionForbiddenError)
+          .addError(PaymentProviderConfigurationServiceError)
+      )
+      .middleware(AuthMiddleware)
+      .prefix("/payment-provider-configurations")
+  )
+  .add(
+    HttpApiGroup.make("payment_provider_products")
+      .add(
+        HttpApiEndpoint.get("listPaymentProviderProducts")`/`
+          .addSuccess(Schema.Array(PaymentProviderProduct))
+          .addError(ActionForbiddenError)
+          .addError(PaymentProviderProductServiceError)
+      )
+      .middleware(AuthMiddleware)
+      .prefix("/payment-provider-products")
+  )
+  .add(
+    HttpApiGroup.make("changesets")
+      .add(
+        HttpApiEndpoint.post("deployChangeset")`/deploy`
+          .setPayload(DeployChangesetBody)
+          .addSuccess(DeployChangesetResponse)
+          .addError(AuthenticationError)
+          .addError(ActionForbiddenError)
+          .addError(ChangesetDeploymentServiceError)
+      )
+      .middleware(AuthMiddleware)
+      .prefix("/changesets")
+  )
+  .add(
+    HttpApiGroup.make("webhooks")
+      .add(
+        HttpApiEndpoint.post("createWebhookEndpoint")`/endpoints`
+          .setPayload(CreateWebhookEndpointBody)
+          .addSuccess(WebhookEndpoint)
+          .addError(ActionForbiddenError)
+          .addError(WebhookValidationError)
+          .addError(WebhookServiceError)
+      )
+      .add(
+        HttpApiEndpoint.get("listWebhookEndpoints")`/endpoints`
+          .addSuccess(Schema.Array(WebhookEndpoint))
+          .addError(ActionForbiddenError)
+          .addError(WebhookServiceError)
+      )
+      .add(
+        HttpApiEndpoint.get("getWebhookEndpoint")`/endpoints/${WebhookEndpointIdParam}`
+          .addSuccess(WebhookEndpoint)
+          .addError(ActionForbiddenError)
+          .addError(WebhookEndpointNotFoundError)
+          .addError(WebhookServiceError)
+      )
+      .add(
+        HttpApiEndpoint.patch("updateWebhookEndpoint")`/endpoints/${WebhookEndpointIdParam}`
+          .setPayload(UpdateWebhookEndpointBody)
+          .addSuccess(WebhookEndpoint)
+          .addError(ActionForbiddenError)
+          .addError(WebhookEndpointNotFoundError)
+          .addError(WebhookValidationError)
+          .addError(WebhookServiceError)
+      )
+      .add(
+        HttpApiEndpoint.del("deleteWebhookEndpoint")`/endpoints/${WebhookEndpointIdParam}`
+          .addError(ActionForbiddenError)
+          .addError(WebhookEndpointNotFoundError)
+          .addError(WebhookServiceError)
+      )
+      .add(
+        HttpApiEndpoint.post("rotateWebhookSecret")`/endpoints/${WebhookEndpointIdParam}/rotate-secret`
+          .addSuccess(WebhookEndpoint)
+          .addError(ActionForbiddenError)
+          .addError(WebhookEndpointNotFoundError)
+          .addError(WebhookServiceError)
+      )
+      .add(
+        HttpApiEndpoint.post("testWebhookEndpoint")`/endpoints/${WebhookEndpointIdParam}/test`
+          .addSuccess(WebhookDelivery)
+          .addError(ActionForbiddenError)
+          .addError(WebhookEndpointNotFoundError)
+          .addError(WebhookServiceError)
+      )
+      .add(
+        HttpApiEndpoint.get("listWebhookDeliveries")`/deliveries`
+          .addSuccess(Schema.Array(WebhookDelivery))
+          .addError(ActionForbiddenError)
+          .addError(WebhookServiceError)
+      )
+      .add(
+        HttpApiEndpoint.get("getWebhookDelivery")`/deliveries/${WebhookDeliveryIdParam}`
+          .addSuccess(WebhookDeliveryWithAttempts)
+          .addError(ActionForbiddenError)
+          .addError(WebhookDeliveryNotFoundError)
+          .addError(WebhookServiceError)
+      )
+      .add(
+        HttpApiEndpoint.post("retryWebhookDelivery")`/deliveries/${WebhookDeliveryIdParam}/retry`
+          .addSuccess(WebhookDelivery)
+          .addError(ActionForbiddenError)
+          .addError(WebhookDeliveryNotFoundError)
+          .addError(WebhookValidationError)
+          .addError(WebhookServiceError)
+      )
+      .middleware(AuthMiddleware)
+      .prefix("/webhooks")
+  )
+
+  .prefix("/api/v1");

package/src/auth.ts

@@ -0,0 +1,102 @@
+import { Context, Schema } from "effect";
+
+// ============================================================================
+// Session Sub-Schemas
+// ============================================================================
+
+export const ApiSessionOrganizationSchema = Schema.Struct({
+  id: Schema.String,
+  name: Schema.String,
+  permissions: Schema.Array(Schema.String),
+  slug: Schema.String,
+});
+
+export const ApiSessionProjectSchema = Schema.Struct({
+  id: Schema.String,
+  name: Schema.String,
+  organizationId: Schema.String,
+  permissions: Schema.Array(Schema.String),
+  slug: Schema.String,
+});
+
+const ApiSessionOrganizationsSchema = Schema.Array(ApiSessionOrganizationSchema);
+const ApiSessionProjectsSchema = Schema.Array(ApiSessionProjectSchema);
+
+export const ApiSessionCustomerSchema = Schema.Struct({
+  appUserId: Schema.String,
+});
+
+export const ApiSessionUserSchema = Schema.Struct({
+  createdAt: Schema.Date,
+  email: Schema.String,
+  emailVerified: Schema.Boolean,
+  id: Schema.String,
+  image: Schema.NullOr(Schema.String),
+  name: Schema.String,
+  updatedAt: Schema.Date,
+});
+
+// ============================================================================
+// Session Type Schemas
+// ============================================================================
+
+export const ApiUserSessionSchema = Schema.Struct({
+  cookie: Schema.NullOr(Schema.String),
+  customer: Schema.Null,
+  method: Schema.Literal("user"),
+  name: Schema.String,
+  organizations: ApiSessionOrganizationsSchema,
+  projects: ApiSessionProjectsSchema,
+  user: ApiSessionUserSchema,
+});
+
+export const ApiSecretKeySessionSchema = Schema.Struct({
+  cookie: Schema.Null,
+  customer: Schema.Null,
+  method: Schema.Literal("secret-key"),
+  name: Schema.String,
+  organizations: ApiSessionOrganizationsSchema,
+  projects: ApiSessionProjectsSchema,
+  user: Schema.Null,
+});
+
+export const ApiPublishableKeySessionSchema = Schema.Struct({
+  cookie: Schema.Null,
+  customer: ApiSessionCustomerSchema,
+  method: Schema.Literal("publishable-key"),
+  name: Schema.String,
+  organizations: ApiSessionOrganizationsSchema,
+  projects: ApiSessionProjectsSchema,
+  user: Schema.Null,
+});
+
+// ============================================================================
+// Combined Auth Session Schema
+// ============================================================================
+
+export const ApiAuthSessionSchema = Schema.Union(
+  ApiUserSessionSchema,
+  ApiSecretKeySessionSchema,
+  ApiPublishableKeySessionSchema
+);
+
+// ============================================================================
+// Type Exports
+// ============================================================================
+
+export type ApiUserSession = typeof ApiUserSessionSchema.Type;
+export type ApiSecretKeySession = typeof ApiSecretKeySessionSchema.Type;
+export type ApiPublishableKeySession = typeof ApiPublishableKeySessionSchema.Type;
+export type AnyApiAuthSession =
+  | ApiUserSession
+  | ApiSecretKeySession
+  | ApiPublishableKeySession;
+
+// ============================================================================
+// Context Tag
+// ============================================================================
+
+export class ApiAuthSession extends Context.Tag("api-spec/auth/ApiAuthSession")<
+  ApiAuthSession,
+  ApiUserSession | ApiSecretKeySession | ApiPublishableKeySession
+>() {}