@wenlarge/ostrol-communication 0.5.0

package/dist/pagination/cursor.js

@@ -0,0 +1,42 @@
+"use strict";
+// Keyset (seek) cursor pagination shared by every list endpoint. The cursor is an
+// opaque base64url of the last row's sort key { v, id } where v is the ordering
+// value (createdAt / publishedAt ISO string). The (v, id) tuple keeps paging stable
+// across rows that share a timestamp. See backend-structure pagination section.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.encodeCursor = encodeCursor;
+exports.decodeCursor = decodeCursor;
+exports.clampLimit = clampLimit;
+exports.buildCursorPage = buildCursorPage;
+function encodeCursor(v, id) {
+    return Buffer.from(JSON.stringify({ v, id }), "utf8").toString("base64url");
+}
+function decodeCursor(cursor) {
+    if (!cursor)
+        return null;
+    try {
+        const parsed = JSON.parse(Buffer.from(cursor, "base64url").toString("utf8"));
+        if (typeof parsed?.v === "string" && typeof parsed?.id === "string") {
+            return { v: parsed.v, id: parsed.id };
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+// Clamps a requested page size into [1, max] with a default fallback.
+function clampLimit(limit, max = 50, def = 20) {
+    if (!Number.isFinite(limit) || limit <= 0)
+        return def;
+    return Math.min(Math.floor(limit), max);
+}
+// Builds a CursorResponse from rows fetched with `LIMIT limit + 1`: the extra row
+// signals hasMore and is dropped; nextCursor is derived from the last kept row.
+function buildCursorPage(rows, limit, toKey) {
+    const hasMore = rows.length > limit;
+    const data = hasMore ? rows.slice(0, limit) : rows;
+    const last = data[data.length - 1];
+    const nextCursor = hasMore && last ? encodeCursor(toKey(last).v, toKey(last).id) : null;
+    return { data, nextCursor, hasMore };
+}

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@wenlarge/ostrol-communication",
+  "version": "0.5.0",
+  "description": "Shared gRPC proto contracts, generated clients and Kafka helpers for Ostrol microservices.",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "proto",
+    "src/generated"
+  ],
+  "scripts": {
+    "proto:build": "protoc --plugin=protoc-gen-ts_proto=./node_modules/.bin/protoc-gen-ts_proto --proto_path=proto --ts_proto_out=src/generated proto/*.proto --ts_proto_opt=nestJs=true,esModuleInterop=true,forceLong=string,useOptionals=messages,useDate=true,addGrpcMetadata=true,stringEnums=true",
+    "build": "npm run proto:build && tsc",
+    "clean": "rm -rf dist src/generated",
+    "prepare": "npm run build"
+  },
+  "keywords": [
+    "nestjs",
+    "grpc",
+    "proto",
+    "kafka",
+    "typescript",
+    "microservices",
+    "ostrol"
+  ],
+  "author": "Kerem Çakır <kerem.cakirr@gmail.com>",
+  "license": "UNLICENSED",
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@grpc/grpc-js": "^1.14.1",
+    "@grpc/proto-loader": "^0.7.15",
+    "rxjs": "^7.8.1"
+  },
+  "devDependencies": {
+    "@nestjs/common": "^10.4.20",
+    "@nestjs/microservices": "^10.4.20",
+    "@types/node": "^24.9.1",
+    "ts-proto": "^1.181.2",
+    "typescript": "^5.3.3"
+  },
+  "peerDependencies": {
+    "@grpc/grpc-js": "^1.14.1",
+    "@nestjs/common": "^10.x",
+    "@nestjs/microservices": "^10.x"
+  }
+}

package/proto/astro_engine.proto

@@ -0,0 +1,60 @@
+syntax = "proto3";
+
+import "google/protobuf/struct.proto";
+
+package astro_engine;
+
+// Implemented by the PYTHON astro-engine service (Kerykeion). Pure compute:
+// no DB, no Kafka, stateless. Called only by the astrology service's workers.
+// astro-engine generates its stubs from THIS file via grpc_tools.protoc; it does
+// not install the npm package. Complex outputs are returned as Struct (JSON) to
+// avoid pinning a rigid schema onto Kerykeion's output shape.
+service AstroEngineService {
+  rpc ComputeNatal (ComputeNatalRequest) returns (ComputeNatalResponse);
+  rpc ComputeTransits (ComputeTransitsRequest) returns (ComputeTransitsResponse);
+  rpc ForecastTransits (ForecastTransitsRequest) returns (ForecastTransitsResponse);
+}
+
+message ComputeNatalRequest {
+  reserved 2;                    // was `timezone`; now derived from lat/lng in astro-engine
+  reserved "timezone";
+  string birthAt = 1;            // ISO 8601
+  double lat = 3;
+  double lng = 4;
+}
+
+message ComputeNatalResponse {
+  google.protobuf.Struct rawData = 1;       // full chart
+  google.protobuf.Struct natalPoints = 2;   // points cached for transit checks
+  string timezone = 3;                      // IANA zone resolved from lat/lng, e.g. "Europe/Istanbul"
+}
+
+message ComputeTransitsRequest {
+  google.protobuf.Struct natalPoints = 1;   // cached natal points
+  string at = 2;                            // ISO 8601 moment to compute the sky for
+}
+
+message ComputeTransitsResponse {
+  google.protobuf.Struct transits = 1;      // current positions
+  google.protobuf.Struct aspects = 2;       // aspects-to-natal within orb
+}
+
+// Deterministic forecast: every exact transit aspect to the natal points across
+// [fromAt, toAt]. Drives the precomputed transit_event schedule.
+message ForecastTransitsRequest {
+  google.protobuf.Struct natalPoints = 1;
+  string fromAt = 2;                        // ISO 8601
+  string toAt = 3;                          // ISO 8601
+}
+
+message TransitAspect {
+  string transitingBody = 1;                // e.g. "mars"
+  string natalPoint = 2;                    // e.g. "sun"
+  string aspect = 3;                        // e.g. "conjunction"
+  string exactAt = 4;                       // ISO 8601 — trigger time
+  double orb = 5;
+}
+
+message ForecastTransitsResponse {
+  repeated TransitAspect events = 1;
+}

package/proto/astrology.proto

@@ -0,0 +1,78 @@
+syntax = "proto3";
+
+import "google/protobuf/struct.proto";
+import "common.proto";
+
+package astrology;
+
+service AstrologyService {
+  rpc FindManyPost (FindManyPostRequest) returns (FindManyPostResponse);
+  rpc FindFirstPost (FindFirstPostRequest) returns (Post);
+  rpc GetNatalChart (GetNatalChartRequest) returns (NatalChart);
+}
+
+enum PostType {
+  POST_TYPE_UNSPECIFIED = 0;
+  GENERAL = 1;            // userId empty; canonical English post + per-language translation rows
+  DAILY = 2;
+  WEEKLY = 3;
+  MONTHLY = 4;
+  TRANSIT_ALERT = 5;
+}
+
+enum CalculationStatus {
+  CALCULATION_STATUS_UNSPECIFIED = 0;
+  PENDING = 1;
+  IN_PROGRESS = 2;
+  DONE = 3;
+  FAILED = 4;
+}
+
+message Post {
+  string id = 1;
+  string userId = 2;             // empty => general
+  PostType type = 3;
+  string title = 4;
+  string content = 5;
+  string language = 6;           // general posts: "en"; personal posts: user's language at generation time
+  common.Plan plan = 7;
+  bool shouldNotify = 8;
+  string publishedAt = 9;        // ISO 8601
+  string createdAt = 10;         // ISO 8601
+  string sourcePostId = 11;      // translations: id of the canonical (English) post; empty on canonical/personal posts
+}
+
+message NatalChart {
+  string id = 1;
+  string userId = 2;
+  google.protobuf.Struct rawData = 3;
+  google.protobuf.Struct natalPoints = 4;
+  CalculationStatus status = 5;
+  string summary = 6;
+  string deepSummary = 7;
+  google.protobuf.Struct personalityScores = 8;
+  string personalitySummary = 9;
+}
+
+// GENERAL feed: userId left empty. Personal types: userId set (caller).
+message FindManyPostRequest {
+  common.CursorRequest page = 1;
+  PostType type = 2;
+  string userId = 3;
+  string language = 4;           // GENERAL only: language variant to return; empty => "en"
+}
+
+message FindManyPostResponse {
+  repeated Post data = 1;
+  string nextCursor = 2;
+  bool hasMore = 3;
+}
+
+message FindFirstPostRequest {
+  string id = 1;                 // canonical post id (GENERAL translations are addressed via their canonical id)
+  string language = 2;           // GENERAL only: preferred translation; falls back to the canonical post when absent
+}
+
+message GetNatalChartRequest {
+  string userId = 1;
+}

package/proto/auth.proto

@@ -0,0 +1,123 @@
+syntax = "proto3";
+
+import "google/protobuf/empty.proto";
+import "common.proto";
+
+package auth;
+
+service AuthService {
+  rpc Register (RegisterRequest) returns (AuthResponse);
+  rpc Login (LoginRequest) returns (AuthResponse);
+  rpc OAuthLogin (OAuthLoginRequest) returns (AuthResponse);
+  rpc RefreshToken (RefreshTokenRequest) returns (AuthResponse);
+  rpc UpdateProfile (UpdateProfileRequest) returns (AuthResponse);
+  rpc OAuthLink (OAuthLinkRequest) returns (google.protobuf.Empty);
+  rpc OAuthUnlink (OAuthUnlinkRequest) returns (google.protobuf.Empty);
+  rpc GetUser (GetUserRequest) returns (User);
+  rpc UpdateUserPlan (UpdateUserPlanRequest) returns (google.protobuf.Empty);
+  rpc DeleteAccount (DeleteAccountRequest) returns (google.protobuf.Empty);
+}
+
+enum OAuthProvider {
+  OAUTH_PROVIDER_UNSPECIFIED = 0;
+  GOOGLE = 1;
+  MICROSOFT = 2;
+}
+
+enum UserStatus {
+  USER_STATUS_UNSPECIFIED = 0;
+  ACTIVE = 1;
+  SUSPENDED = 2;
+  DELETED = 3;
+}
+
+message User {
+  reserved 6;                    // was `birthTimezone`; timezone is derived from lat/lng in astro-engine
+  reserved "birthTimezone";
+  string id = 1;
+  string email = 2;
+  bool emailVerified = 3;
+  string name = 4;
+  string birthAt = 5;            // ISO 8601, empty if unset
+  string language = 7;           // BCP-47
+  double birthLat = 8;
+  double birthLng = 9;
+  string birthLocationName = 10;
+  common.Plan plan = 11;
+  UserStatus status = 12;
+  repeated OAuthProvider linkedProviders = 13;
+  // Current IANA timezone (device-reported, e.g. "Europe/Istanbul"), empty if
+  // unset. NOT the birth timezone — that stays server-derived from lat/lng.
+  string timezone = 14;
+}
+
+message AuthResponse {
+  string accessToken = 1;        // RS256 JWT, short TTL
+  string refreshToken = 2;       // revocable, Redis-backed
+  User user = 3;
+}
+
+message RegisterRequest {
+  string name = 1;
+  string email = 2;
+  string password = 3;
+  string language = 4;
+  string timezone = 5;           // current IANA timezone (device-reported), optional
+}
+
+message LoginRequest {
+  string email = 1;
+  string password = 2;
+}
+
+message OAuthLoginRequest {
+  OAuthProvider provider = 1;
+  string providerToken = 2;
+  string language = 3;
+  string timezone = 4;           // current IANA timezone (device-reported), optional
+}
+
+message RefreshTokenRequest {
+  string refreshToken = 1;
+}
+
+message UpdateProfileRequest {
+  reserved 4;                    // was `birthTimezone`; timezone is derived from lat/lng in astro-engine
+  reserved "birthTimezone";
+  // Partial update: every field except userId is `optional` so absence is
+  // distinguishable from proto3 defaults ("" / 0). Without presence tracking a
+  // language-only PATCH used to arrive with birthLat=0/birthLng=0 and silently
+  // overwrite the stored birth coordinates.
+  string userId = 1;             // caller, from gateway
+  optional string name = 2;
+  optional string birthAt = 3;
+  optional double birthLat = 5;
+  optional double birthLng = 6;
+  optional string birthLocationName = 7;
+  optional string language = 8;
+  optional string timezone = 9;  // current IANA timezone; never triggers a natal recalc
+}
+
+message OAuthLinkRequest {
+  string userId = 1;
+  OAuthProvider provider = 2;
+  string providerToken = 3;
+}
+
+message OAuthUnlinkRequest {
+  string userId = 1;
+  OAuthProvider provider = 2;
+}
+
+message GetUserRequest {
+  string userId = 1;
+}
+
+message UpdateUserPlanRequest {
+  string userId = 1;
+  common.Plan plan = 2;
+}
+
+message DeleteAccountRequest {
+  string userId = 1;
+}

package/proto/billing.proto

@@ -0,0 +1,56 @@
+syntax = "proto3";
+
+import "google/protobuf/empty.proto";
+import "common.proto";
+
+package billing;
+
+service BillingService {
+  rpc GetSubscription (GetSubscriptionRequest) returns (Subscription);
+  rpc CreateCheckoutSession (CreateCheckoutSessionRequest) returns (CheckoutSession);
+  rpc CreatePortalSession (CreatePortalSessionRequest) returns (PortalSession);
+  rpc HandleWebhookEvent (WebhookEventRequest) returns (google.protobuf.Empty);
+}
+
+enum SubscriptionStatus {
+  SUBSCRIPTION_STATUS_UNSPECIFIED = 0;
+  ACTIVE = 1;
+  PAST_DUE = 2;
+  CANCELLED = 3;
+  EXPIRED = 4;
+}
+
+message Subscription {
+  string id = 1;
+  string userId = 2;
+  common.Plan plan = 3;
+  SubscriptionStatus status = 4;
+  bool cancelAtPeriodEnd = 5;
+  string currentPeriodStart = 6;   // ISO 8601
+  string currentPeriodEnd = 7;     // ISO 8601
+}
+
+message GetSubscriptionRequest {
+  string userId = 1;
+}
+
+message CreateCheckoutSessionRequest {
+  string userId = 1;
+}
+
+message CreatePortalSessionRequest {
+  string userId = 1;
+}
+
+message CheckoutSession {
+  string checkoutUrl = 1;          // Stripe checkout page
+}
+
+message PortalSession {
+  string portalUrl = 1;            // Stripe customer portal
+}
+
+message WebhookEventRequest {
+  bytes payload = 1;               // raw Stripe webhook body
+  string signature = 2;            // Stripe-Signature header
+}

package/proto/common.proto

@@ -0,0 +1,17 @@
+syntax = "proto3";
+
+package common;
+
+enum Plan {
+  PLAN_UNSPECIFIED = 0;
+  FREE = 1;
+  PREMIUM = 2;
+}
+
+// Keyset (seek) cursor pagination request. `cursor` is an opaque base64 of the
+// last row's sort key ({ v, id }); empty on the first page. `limit` is capped
+// server-side (e.g. <= 50). See cursor.ts encode/decode helpers.
+message CursorRequest {
+  string cursor = 1;
+  int32 limit = 2;
+}

package/src/generated/astro_engine.ts

@@ -0,0 +1,144 @@
+// Code generated by protoc-gen-ts_proto. DO NOT EDIT.
+// versions:
+//   protoc-gen-ts_proto  v1.181.2
+//   protoc               v3.21.5
+// source: astro_engine.proto
+
+/* eslint-disable */
+import { Metadata } from "@grpc/grpc-js";
+import { GrpcMethod, GrpcStreamMethod } from "@nestjs/microservices";
+import { wrappers } from "protobufjs";
+import { Observable } from "rxjs";
+import { Struct } from "./google/protobuf/struct";
+
+export const protobufPackage = "astro_engine";
+
+export interface ComputeNatalRequest {
+  /** ISO 8601 */
+  birthAt: string;
+  lat: number;
+  lng: number;
+}
+
+export interface ComputeNatalResponse {
+  /** full chart */
+  rawData?:
+    | { [key: string]: any }
+    | undefined;
+  /** points cached for transit checks */
+  natalPoints?:
+    | { [key: string]: any }
+    | undefined;
+  /** IANA zone resolved from lat/lng, e.g. "Europe/Istanbul" */
+  timezone: string;
+}
+
+export interface ComputeTransitsRequest {
+  /** cached natal points */
+  natalPoints?:
+    | { [key: string]: any }
+    | undefined;
+  /** ISO 8601 moment to compute the sky for */
+  at: string;
+}
+
+export interface ComputeTransitsResponse {
+  /** current positions */
+  transits?:
+    | { [key: string]: any }
+    | undefined;
+  /** aspects-to-natal within orb */
+  aspects?: { [key: string]: any } | undefined;
+}
+
+/**
+ * Deterministic forecast: every exact transit aspect to the natal points across
+ * [fromAt, toAt]. Drives the precomputed transit_event schedule.
+ */
+export interface ForecastTransitsRequest {
+  natalPoints?:
+    | { [key: string]: any }
+    | undefined;
+  /** ISO 8601 */
+  fromAt: string;
+  /** ISO 8601 */
+  toAt: string;
+}
+
+export interface TransitAspect {
+  /** e.g. "mars" */
+  transitingBody: string;
+  /** e.g. "sun" */
+  natalPoint: string;
+  /** e.g. "conjunction" */
+  aspect: string;
+  /** ISO 8601 — trigger time */
+  exactAt: string;
+  orb: number;
+}
+
+export interface ForecastTransitsResponse {
+  events: TransitAspect[];
+}
+
+export const ASTRO_ENGINE_PACKAGE_NAME = "astro_engine";
+
+wrappers[".google.protobuf.Struct"] = { fromObject: Struct.wrap, toObject: Struct.unwrap } as any;
+
+/**
+ * Implemented by the PYTHON astro-engine service (Kerykeion). Pure compute:
+ * no DB, no Kafka, stateless. Called only by the astrology service's workers.
+ * astro-engine generates its stubs from THIS file via grpc_tools.protoc; it does
+ * not install the npm package. Complex outputs are returned as Struct (JSON) to
+ * avoid pinning a rigid schema onto Kerykeion's output shape.
+ */
+
+export interface AstroEngineServiceClient {
+  computeNatal(request: ComputeNatalRequest, metadata?: Metadata): Observable<ComputeNatalResponse>;
+
+  computeTransits(request: ComputeTransitsRequest, metadata?: Metadata): Observable<ComputeTransitsResponse>;
+
+  forecastTransits(request: ForecastTransitsRequest, metadata?: Metadata): Observable<ForecastTransitsResponse>;
+}
+
+/**
+ * Implemented by the PYTHON astro-engine service (Kerykeion). Pure compute:
+ * no DB, no Kafka, stateless. Called only by the astrology service's workers.
+ * astro-engine generates its stubs from THIS file via grpc_tools.protoc; it does
+ * not install the npm package. Complex outputs are returned as Struct (JSON) to
+ * avoid pinning a rigid schema onto Kerykeion's output shape.
+ */
+
+export interface AstroEngineServiceController {
+  computeNatal(
+    request: ComputeNatalRequest,
+    metadata?: Metadata,
+  ): Promise<ComputeNatalResponse> | Observable<ComputeNatalResponse> | ComputeNatalResponse;
+
+  computeTransits(
+    request: ComputeTransitsRequest,
+    metadata?: Metadata,
+  ): Promise<ComputeTransitsResponse> | Observable<ComputeTransitsResponse> | ComputeTransitsResponse;
+
+  forecastTransits(
+    request: ForecastTransitsRequest,
+    metadata?: Metadata,
+  ): Promise<ForecastTransitsResponse> | Observable<ForecastTransitsResponse> | ForecastTransitsResponse;
+}
+
+export function AstroEngineServiceControllerMethods() {
+  return function (constructor: Function) {
+    const grpcMethods: string[] = ["computeNatal", "computeTransits", "forecastTransits"];
+    for (const method of grpcMethods) {
+      const descriptor: any = Reflect.getOwnPropertyDescriptor(constructor.prototype, method);
+      GrpcMethod("AstroEngineService", method)(constructor.prototype[method], method, descriptor);
+    }
+    const grpcStreamMethods: string[] = [];
+    for (const method of grpcStreamMethods) {
+      const descriptor: any = Reflect.getOwnPropertyDescriptor(constructor.prototype, method);
+      GrpcStreamMethod("AstroEngineService", method)(constructor.prototype[method], method, descriptor);
+    }
+  };
+}
+
+export const ASTRO_ENGINE_SERVICE_NAME = "AstroEngineService";