@sylphx/contract 0.2.0

package/dist/schemas/realtime.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Realtime — BaaS plane pub/sub over Redis Streams. Transport: server-sent
+ * events (SSE) for subscribe; REST for emit / history. Mirrors
+ * `@sylphx/sdk` `realtime.ts`.
+ */
+import { Schema } from 'effect';
+export declare const ChannelName: Schema.brand<Schema.filter<typeof Schema.String>, "ChannelName">;
+export type ChannelName = typeof ChannelName.Type;
+export declare const StreamMessageId: Schema.brand<typeof Schema.String, "StreamMessageId">;
+export type StreamMessageId = typeof StreamMessageId.Type;
+export declare const StreamMessage: Schema.Struct<{
+    id: typeof Schema.String;
+    channel: typeof Schema.String;
+    event: typeof Schema.String;
+    data: typeof Schema.Unknown;
+    timestamp: typeof Schema.Number;
+}>;
+export type StreamMessage = typeof StreamMessage.Type;
+export declare const RealtimeEmitInput: Schema.Struct<{
+    channel: typeof Schema.String;
+    event: typeof Schema.String;
+    data: typeof Schema.Unknown;
+}>;
+export type RealtimeEmitInput = typeof RealtimeEmitInput.Type;
+export declare const RealtimeEmitResult: Schema.Struct<{
+    id: typeof Schema.String;
+    channel: typeof Schema.String;
+}>;
+export type RealtimeEmitResult = typeof RealtimeEmitResult.Type;
+export declare const RealtimeHistoryQuery: Schema.Struct<{
+    channel: typeof Schema.String;
+    limit: Schema.optional<typeof Schema.String>;
+    after: Schema.optional<typeof Schema.String>;
+}>;
+export type RealtimeHistoryQuery = typeof RealtimeHistoryQuery.Type;
+export declare const RealtimeHistoryResult: Schema.Struct<{
+    messages: Schema.Array$<Schema.Struct<{
+        id: typeof Schema.String;
+        channel: typeof Schema.String;
+        event: typeof Schema.String;
+        data: typeof Schema.Unknown;
+        timestamp: typeof Schema.Number;
+    }>>;
+}>;
+export type RealtimeHistoryResult = typeof RealtimeHistoryResult.Type;
+//# sourceMappingURL=realtime.d.ts.map

package/dist/schemas/realtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"realtime.d.ts","sourceRoot":"","sources":["../../src/schemas/realtime.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAA;AAE/B,eAAO,MAAM,WAAW,kEAAuE,CAAA;AAC/F,MAAM,MAAM,WAAW,GAAG,OAAO,WAAW,CAAC,IAAI,CAAA;AAEjD,eAAO,MAAM,eAAe,uDAAsD,CAAA;AAClF,MAAM,MAAM,eAAe,GAAG,OAAO,eAAe,CAAC,IAAI,CAAA;AAEzD,eAAO,MAAM,aAAa;;;;;;EAMxB,CAAA;AACF,MAAM,MAAM,aAAa,GAAG,OAAO,aAAa,CAAC,IAAI,CAAA;AAErD,eAAO,MAAM,iBAAiB;;;;EAI5B,CAAA;AACF,MAAM,MAAM,iBAAiB,GAAG,OAAO,iBAAiB,CAAC,IAAI,CAAA;AAE7D,eAAO,MAAM,kBAAkB;;;EAG7B,CAAA;AACF,MAAM,MAAM,kBAAkB,GAAG,OAAO,kBAAkB,CAAC,IAAI,CAAA;AAE/D,eAAO,MAAM,oBAAoB;;;;EAI/B,CAAA;AACF,MAAM,MAAM,oBAAoB,GAAG,OAAO,oBAAoB,CAAC,IAAI,CAAA;AAEnE,eAAO,MAAM,qBAAqB;;;;;;;;EAEhC,CAAA;AACF,MAAM,MAAM,qBAAqB,GAAG,OAAO,qBAAqB,CAAC,IAAI,CAAA"}

package/dist/schemas/realtime.js

@@ -0,0 +1,32 @@
+/**
+ * Realtime — BaaS plane pub/sub over Redis Streams. Transport: server-sent
+ * events (SSE) for subscribe; REST for emit / history. Mirrors
+ * `@sylphx/sdk` `realtime.ts`.
+ */
+import { Schema } from 'effect';
+export const ChannelName = Schema.String.pipe(Schema.minLength(1), Schema.brand('ChannelName'));
+export const StreamMessageId = Schema.String.pipe(Schema.brand('StreamMessageId'));
+export const StreamMessage = Schema.Struct({
+    id: Schema.String,
+    channel: Schema.String,
+    event: Schema.String,
+    data: Schema.Unknown,
+    timestamp: Schema.Number,
+});
+export const RealtimeEmitInput = Schema.Struct({
+    channel: Schema.String,
+    event: Schema.String,
+    data: Schema.Unknown,
+});
+export const RealtimeEmitResult = Schema.Struct({
+    id: Schema.String,
+    channel: Schema.String,
+});
+export const RealtimeHistoryQuery = Schema.Struct({
+    channel: Schema.String,
+    limit: Schema.optional(Schema.String),
+    after: Schema.optional(Schema.String),
+});
+export const RealtimeHistoryResult = Schema.Struct({
+    messages: Schema.Array(StreamMessage),
+});

package/dist/schemas/referrals-admin.d.ts

@@ -0,0 +1,166 @@
+/**
+ * Referrals Admin — Console-plane referral code management + stats. Distinct
+ * from the BaaS-plane referral redemption surface served by the standalone
+ * runtime; these endpoints operate on platform + per-project DBs and are
+ * reachable by authenticated project members.
+ *
+ * Mirrors the wire shapes served at `/referrals/*` in
+ * `apps/api/src/server/platform/routes/referrals.ts`.
+ */
+import { Schema } from 'effect';
+export declare const ReferralStatus: Schema.Literal<["pending", "completed", "expired"]>;
+export type ReferralStatus = typeof ReferralStatus.Type;
+/**
+ * Reward type — Console admin surface covers the full customer-facing set
+ * (including `credit`), so BaaS + Admin stay consistent.
+ */
+export declare const ReferralRewardType: Schema.Literal<["points", "premium_trial", "discount", "credit"]>;
+export type ReferralRewardType = typeof ReferralRewardType.Type;
+export declare const ReferralUserRef: Schema.Struct<{
+    id: typeof Schema.String;
+    email: typeof Schema.String;
+    name: Schema.NullOr<typeof Schema.String>;
+}>;
+export type ReferralUserRef = typeof ReferralUserRef.Type;
+export declare const Referral: Schema.Struct<{
+    id: typeof Schema.String;
+    projectId: typeof Schema.String;
+    projectName: typeof Schema.String;
+    code: typeof Schema.String;
+    referrer: Schema.NullOr<Schema.Struct<{
+        id: typeof Schema.String;
+        email: typeof Schema.String;
+        name: Schema.NullOr<typeof Schema.String>;
+    }>>;
+    referredUser: Schema.NullOr<Schema.Struct<{
+        id: typeof Schema.String;
+        email: typeof Schema.String;
+        name: Schema.NullOr<typeof Schema.String>;
+    }>>;
+    status: Schema.Literal<["pending", "completed", "expired"]>;
+    rewardType: Schema.Literal<["points", "premium_trial", "discount", "credit"]>;
+    createdAt: typeof Schema.String;
+    completedAt: Schema.NullOr<typeof Schema.String>;
+}>;
+export type Referral = typeof Referral.Type;
+export declare const ReferralDetail: Schema.Struct<{
+    id: typeof Schema.String;
+    projectId: typeof Schema.String;
+    projectName: typeof Schema.String;
+    code: typeof Schema.String;
+    referrer: Schema.NullOr<Schema.Struct<{
+        id: typeof Schema.String;
+        email: typeof Schema.String;
+        name: Schema.NullOr<typeof Schema.String>;
+    }>>;
+    referredUser: Schema.NullOr<Schema.Struct<{
+        id: typeof Schema.String;
+        email: typeof Schema.String;
+        name: Schema.NullOr<typeof Schema.String>;
+    }>>;
+    status: Schema.Literal<["pending", "completed", "expired"]>;
+    rewardType: Schema.Literal<["points", "premium_trial", "discount", "credit"]>;
+    createdAt: typeof Schema.String;
+    completedAt: Schema.NullOr<typeof Schema.String>;
+    metadata: Schema.NullOr<Schema.Record$<typeof Schema.String, typeof Schema.Unknown>>;
+}>;
+export type ReferralDetail = typeof ReferralDetail.Type;
+export declare const ListReferralsQuery: Schema.Struct<{
+    projectId: Schema.optional<typeof Schema.String>;
+    environmentId: Schema.optional<typeof Schema.String>;
+    limit: Schema.optional<typeof Schema.String>;
+    offset: Schema.optional<typeof Schema.String>;
+}>;
+export type ListReferralsQuery = typeof ListReferralsQuery.Type;
+/** `GET /referrals/:id` is scoped to a project via `?projectId=`. */
+export declare const GetReferralQuery: Schema.Struct<{
+    projectId: typeof Schema.String;
+}>;
+export type GetReferralQuery = typeof GetReferralQuery.Type;
+export declare const CreateReferralInput: Schema.Struct<{
+    projectId: typeof Schema.String;
+    referrerId: typeof Schema.String;
+    code: Schema.optional<typeof Schema.String>;
+    rewardType: Schema.optional<Schema.Literal<["points", "premium_trial", "discount", "credit"]>>;
+}>;
+export type CreateReferralInput = typeof CreateReferralInput.Type;
+export declare const GetReferralStatsQuery: Schema.Struct<{
+    projectId: Schema.optional<typeof Schema.String>;
+    environmentId: Schema.optional<typeof Schema.String>;
+    days: Schema.optional<typeof Schema.String>;
+}>;
+export type GetReferralStatsQuery = typeof GetReferralStatsQuery.Type;
+export declare const ExpireReferralInput: Schema.Struct<{
+    projectId: typeof Schema.String;
+}>;
+export type ExpireReferralInput = typeof ExpireReferralInput.Type;
+export declare const ListReferralsResult: Schema.Array$<Schema.Struct<{
+    id: typeof Schema.String;
+    projectId: typeof Schema.String;
+    projectName: typeof Schema.String;
+    code: typeof Schema.String;
+    referrer: Schema.NullOr<Schema.Struct<{
+        id: typeof Schema.String;
+        email: typeof Schema.String;
+        name: Schema.NullOr<typeof Schema.String>;
+    }>>;
+    referredUser: Schema.NullOr<Schema.Struct<{
+        id: typeof Schema.String;
+        email: typeof Schema.String;
+        name: Schema.NullOr<typeof Schema.String>;
+    }>>;
+    status: Schema.Literal<["pending", "completed", "expired"]>;
+    rewardType: Schema.Literal<["points", "premium_trial", "discount", "credit"]>;
+    createdAt: typeof Schema.String;
+    completedAt: Schema.NullOr<typeof Schema.String>;
+}>>;
+export type ListReferralsResult = typeof ListReferralsResult.Type;
+export declare const CreateReferralResult: Schema.Struct<{
+    id: typeof Schema.String;
+    code: typeof Schema.String;
+}>;
+export type CreateReferralResult = typeof CreateReferralResult.Type;
+export declare const ExpireReferralResult: Schema.Struct<{
+    success: typeof Schema.Boolean;
+}>;
+export type ExpireReferralResult = typeof ExpireReferralResult.Type;
+export declare const GetReferralStatsResult: Schema.Struct<{
+    overall: Schema.Struct<{
+        total: typeof Schema.Number;
+        completed: typeof Schema.Number;
+        pending: typeof Schema.Number;
+        expired: typeof Schema.Number;
+        conversionRate: typeof Schema.Number;
+    }>;
+    period: Schema.Struct<{
+        days: typeof Schema.Number;
+        since: typeof Schema.String;
+        created: typeof Schema.Number;
+        completed: typeof Schema.Number;
+        conversionRate: typeof Schema.Number;
+    }>;
+    byRewardType: Schema.Array$<Schema.Struct<{
+        rewardType: Schema.Literal<["points", "premium_trial", "discount", "credit"]>;
+        total: typeof Schema.Number;
+        completed: typeof Schema.Number;
+        conversionRate: typeof Schema.Number;
+    }>>;
+    byProject: Schema.Array$<Schema.Struct<{
+        projectId: typeof Schema.String;
+        total: typeof Schema.Number;
+        completed: typeof Schema.Number;
+        conversionRate: typeof Schema.Number;
+    }>>;
+    dailyTrend: Schema.Array$<Schema.Struct<{
+        date: typeof Schema.String;
+        created: typeof Schema.Number;
+        completed: typeof Schema.Number;
+    }>>;
+    topReferrers: Schema.Array$<Schema.Struct<{
+        referrerId: typeof Schema.String;
+        totalReferrals: typeof Schema.Number;
+        completedReferrals: typeof Schema.Number;
+    }>>;
+}>;
+export type GetReferralStatsResult = typeof GetReferralStatsResult.Type;
+//# sourceMappingURL=referrals-admin.d.ts.map

package/dist/schemas/referrals-admin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"referrals-admin.d.ts","sourceRoot":"","sources":["../../src/schemas/referrals-admin.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAA;AAE/B,eAAO,MAAM,cAAc,qDAAoD,CAAA;AAC/E,MAAM,MAAM,cAAc,GAAG,OAAO,cAAc,CAAC,IAAI,CAAA;AAEvD;;;GAGG;AACH,eAAO,MAAM,kBAAkB,mEAAkE,CAAA;AACjG,MAAM,MAAM,kBAAkB,GAAG,OAAO,kBAAkB,CAAC,IAAI,CAAA;AAE/D,eAAO,MAAM,eAAe;;;;EAI1B,CAAA;AACF,MAAM,MAAM,eAAe,GAAG,OAAO,eAAe,CAAC,IAAI,CAAA;AAEzD,eAAO,MAAM,QAAQ;;;;;;;;;;;;;;;;;;;EAWnB,CAAA;AACF,MAAM,MAAM,QAAQ,GAAG,OAAO,QAAQ,CAAC,IAAI,CAAA;AAE3C,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;;;;EAYzB,CAAA;AACF,MAAM,MAAM,cAAc,GAAG,OAAO,cAAc,CAAC,IAAI,CAAA;AAIvD,eAAO,MAAM,kBAAkB;;;;;EAK7B,CAAA;AACF,MAAM,MAAM,kBAAkB,GAAG,OAAO,kBAAkB,CAAC,IAAI,CAAA;AAE/D,qEAAqE;AACrE,eAAO,MAAM,gBAAgB;;EAE3B,CAAA;AACF,MAAM,MAAM,gBAAgB,GAAG,OAAO,gBAAgB,CAAC,IAAI,CAAA;AAE3D,eAAO,MAAM,mBAAmB;;;;;EAK9B,CAAA;AACF,MAAM,MAAM,mBAAmB,GAAG,OAAO,mBAAmB,CAAC,IAAI,CAAA;AAEjE,eAAO,MAAM,qBAAqB;;;;EAIhC,CAAA;AACF,MAAM,MAAM,qBAAqB,GAAG,OAAO,qBAAqB,CAAC,IAAI,CAAA;AAErE,eAAO,MAAM,mBAAmB;;EAE9B,CAAA;AACF,MAAM,MAAM,mBAAmB,GAAG,OAAO,mBAAmB,CAAC,IAAI,CAAA;AAIjE,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;GAAyB,CAAA;AACzD,MAAM,MAAM,mBAAmB,GAAG,OAAO,mBAAmB,CAAC,IAAI,CAAA;AAEjE,eAAO,MAAM,oBAAoB;;;EAG/B,CAAA;AACF,MAAM,MAAM,oBAAoB,GAAG,OAAO,oBAAoB,CAAC,IAAI,CAAA;AAEnE,eAAO,MAAM,oBAAoB;;EAE/B,CAAA;AACF,MAAM,MAAM,oBAAoB,GAAG,OAAO,oBAAoB,CAAC,IAAI,CAAA;AA8BnE,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAmBjC,CAAA;AACF,MAAM,MAAM,sBAAsB,GAAG,OAAO,sBAAsB,CAAC,IAAI,CAAA"}

package/dist/schemas/referrals-admin.js

@@ -0,0 +1,123 @@
+/**
+ * Referrals Admin — Console-plane referral code management + stats. Distinct
+ * from the BaaS-plane referral redemption surface served by the standalone
+ * runtime; these endpoints operate on platform + per-project DBs and are
+ * reachable by authenticated project members.
+ *
+ * Mirrors the wire shapes served at `/referrals/*` in
+ * `apps/api/src/server/platform/routes/referrals.ts`.
+ */
+import { Schema } from 'effect';
+export const ReferralStatus = Schema.Literal('pending', 'completed', 'expired');
+/**
+ * Reward type — Console admin surface covers the full customer-facing set
+ * (including `credit`), so BaaS + Admin stay consistent.
+ */
+export const ReferralRewardType = Schema.Literal('points', 'premium_trial', 'discount', 'credit');
+export const ReferralUserRef = Schema.Struct({
+    id: Schema.String,
+    email: Schema.String,
+    name: Schema.NullOr(Schema.String),
+});
+export const Referral = Schema.Struct({
+    id: Schema.String,
+    projectId: Schema.String,
+    projectName: Schema.String,
+    code: Schema.String,
+    referrer: Schema.NullOr(ReferralUserRef),
+    referredUser: Schema.NullOr(ReferralUserRef),
+    status: ReferralStatus,
+    rewardType: ReferralRewardType,
+    createdAt: Schema.String,
+    completedAt: Schema.NullOr(Schema.String),
+});
+export const ReferralDetail = Schema.Struct({
+    id: Schema.String,
+    projectId: Schema.String,
+    projectName: Schema.String,
+    code: Schema.String,
+    referrer: Schema.NullOr(ReferralUserRef),
+    referredUser: Schema.NullOr(ReferralUserRef),
+    status: ReferralStatus,
+    rewardType: ReferralRewardType,
+    createdAt: Schema.String,
+    completedAt: Schema.NullOr(Schema.String),
+    metadata: Schema.NullOr(Schema.Record({ key: Schema.String, value: Schema.Unknown })),
+});
+// ── Requests ───────────────────────────────────────────────────────────────
+export const ListReferralsQuery = Schema.Struct({
+    projectId: Schema.optional(Schema.String),
+    environmentId: Schema.optional(Schema.String),
+    limit: Schema.optional(Schema.String),
+    offset: Schema.optional(Schema.String),
+});
+/** `GET /referrals/:id` is scoped to a project via `?projectId=`. */
+export const GetReferralQuery = Schema.Struct({
+    projectId: Schema.String,
+});
+export const CreateReferralInput = Schema.Struct({
+    projectId: Schema.String,
+    referrerId: Schema.String,
+    code: Schema.optional(Schema.String),
+    rewardType: Schema.optional(ReferralRewardType),
+});
+export const GetReferralStatsQuery = Schema.Struct({
+    projectId: Schema.optional(Schema.String),
+    environmentId: Schema.optional(Schema.String),
+    days: Schema.optional(Schema.String),
+});
+export const ExpireReferralInput = Schema.Struct({
+    projectId: Schema.String,
+});
+// ── Responses ──────────────────────────────────────────────────────────────
+export const ListReferralsResult = Schema.Array(Referral);
+export const CreateReferralResult = Schema.Struct({
+    id: Schema.String,
+    code: Schema.String,
+});
+export const ExpireReferralResult = Schema.Struct({
+    success: Schema.Boolean,
+});
+// ── Stats sub-shapes ───────────────────────────────────────────────────────
+const DailyTrendEntry = Schema.Struct({
+    date: Schema.String,
+    created: Schema.Number,
+    completed: Schema.Number,
+});
+const ByRewardTypeEntry = Schema.Struct({
+    rewardType: ReferralRewardType,
+    total: Schema.Number,
+    completed: Schema.Number,
+    conversionRate: Schema.Number,
+});
+const ByProjectEntry = Schema.Struct({
+    projectId: Schema.String,
+    total: Schema.Number,
+    completed: Schema.Number,
+    conversionRate: Schema.Number,
+});
+const TopReferrerEntry = Schema.Struct({
+    referrerId: Schema.String,
+    totalReferrals: Schema.Number,
+    completedReferrals: Schema.Number,
+});
+export const GetReferralStatsResult = Schema.Struct({
+    overall: Schema.Struct({
+        total: Schema.Number,
+        completed: Schema.Number,
+        pending: Schema.Number,
+        expired: Schema.Number,
+        conversionRate: Schema.Number,
+    }),
+    period: Schema.Struct({
+        days: Schema.Number,
+        since: Schema.String,
+        created: Schema.Number,
+        completed: Schema.Number,
+        conversionRate: Schema.Number,
+    }),
+    byRewardType: Schema.Array(ByRewardTypeEntry),
+    byProject: Schema.Array(ByProjectEntry),
+    dailyTrend: Schema.Array(DailyTrendEntry),
+    topReferrers: Schema.Array(TopReferrerEntry),
+});

package/dist/schemas/referrals.d.ts

@@ -0,0 +1,148 @@
+/**
+ * Referrals — BaaS-plane schemas for the customer-facing referral runtime.
+ * Mirrors the wire shapes served by the deployed-app runtime at
+ * `/referrals/code`, `/referrals/code/regenerate`, `/referrals/stats`,
+ * `/referrals/redeem`, `/referrals/leaderboard` (see
+ * `apps/runtime/src/server/runtime/routes/referrals.ts`).
+ *
+ * Distinct from:
+ *   • `referrals-admin` — super-admin cross-project view
+ *   • `organization-referrals` — Console org read-only program view
+ *
+ * These endpoints are consumed by deployed applications via `@sylphx/sdk`.
+ */
+import { Schema } from 'effect';
+/** Runtime status a referral code can report back to end users. */
+export declare const ReferralCodeStatus: Schema.Literal<["pending", "completed", "expired"]>;
+export type ReferralCodeStatus = typeof ReferralCodeStatus.Type;
+/** Leaderboard window reported by `GET /referrals/leaderboard`. */
+export declare const ReferralLeaderboardPeriod: Schema.Literal<["all", "month", "week"]>;
+export type ReferralLeaderboardPeriod = typeof ReferralLeaderboardPeriod.Type;
+/**
+ * Runtime reward types. Mirrors the contract at `referrals-admin` but kept
+ * as its own declaration so BaaS-plane consumers needn't pull the admin
+ * namespace transitively.
+ */
+export declare const ReferralRewardKind: Schema.Literal<["points", "premium_trial", "discount", "credit"]>;
+export type ReferralRewardKind = typeof ReferralRewardKind.Type;
+/** Reward for one side (referrer or referee) of a redemption. */
+export declare const ReferralRewardConfig: Schema.Struct<{
+    type: Schema.Literal<["points", "premium_trial", "discount", "credit"]>;
+    points: Schema.optional<typeof Schema.Number>;
+    days: Schema.optional<typeof Schema.Number>;
+    discountPercent: Schema.optional<typeof Schema.Number>;
+    creditCents: Schema.optional<typeof Schema.Number>;
+}>;
+export type ReferralRewardConfig = typeof ReferralRewardConfig.Type;
+/**
+ * Inline defaults passed with a redemption request. Console-configured
+ * rewards win if present; otherwise these defaults are auto-discovered
+ * (ADR-004).
+ */
+export declare const ReferralRewardDefaults: Schema.Struct<{
+    referrerReward: Schema.optional<Schema.Struct<{
+        type: Schema.Literal<["points", "premium_trial", "discount", "credit"]>;
+        points: Schema.optional<typeof Schema.Number>;
+        days: Schema.optional<typeof Schema.Number>;
+        discountPercent: Schema.optional<typeof Schema.Number>;
+        creditCents: Schema.optional<typeof Schema.Number>;
+    }>>;
+    refereeReward: Schema.optional<Schema.Struct<{
+        type: Schema.Literal<["points", "premium_trial", "discount", "credit"]>;
+        points: Schema.optional<typeof Schema.Number>;
+        days: Schema.optional<typeof Schema.Number>;
+        discountPercent: Schema.optional<typeof Schema.Number>;
+        creditCents: Schema.optional<typeof Schema.Number>;
+    }>>;
+    doubleReward: Schema.optional<typeof Schema.Boolean>;
+    minimumDaysBeforeReward: Schema.optional<typeof Schema.Number>;
+}>;
+export type ReferralRewardDefaults = typeof ReferralRewardDefaults.Type;
+/** `GET /referrals/code` — returns (or creates) the caller's referral code. */
+export declare const GetCodeResponse: Schema.Struct<{
+    code: typeof Schema.String;
+    status: Schema.Literal<["pending", "completed", "expired"]>;
+}>;
+export type GetCodeResponse = typeof GetCodeResponse.Type;
+/** `POST /referrals/code/regenerate` — rotates the caller's code. */
+export declare const RegenerateCodeResponse: Schema.Struct<{
+    code: typeof Schema.String;
+    totalReferrals: typeof Schema.Number;
+    completedReferrals: typeof Schema.Number;
+    pendingReferrals: typeof Schema.Number;
+}>;
+export type RegenerateCodeResponse = typeof RegenerateCodeResponse.Type;
+/** `GET /referrals/stats` — caller's personal referral counters. */
+export declare const GetStatsResponse: Schema.Struct<{
+    totalReferrals: typeof Schema.Number;
+    completedReferrals: typeof Schema.Number;
+    pendingReferrals: typeof Schema.Number;
+}>;
+export type GetStatsResponse = typeof GetStatsResponse.Type;
+/** `POST /referrals/redeem` request body. */
+export declare const RedeemRequest: Schema.Struct<{
+    code: typeof Schema.String;
+    defaults: Schema.optional<Schema.Struct<{
+        referrerReward: Schema.optional<Schema.Struct<{
+            type: Schema.Literal<["points", "premium_trial", "discount", "credit"]>;
+            points: Schema.optional<typeof Schema.Number>;
+            days: Schema.optional<typeof Schema.Number>;
+            discountPercent: Schema.optional<typeof Schema.Number>;
+            creditCents: Schema.optional<typeof Schema.Number>;
+        }>>;
+        refereeReward: Schema.optional<Schema.Struct<{
+            type: Schema.Literal<["points", "premium_trial", "discount", "credit"]>;
+            points: Schema.optional<typeof Schema.Number>;
+            days: Schema.optional<typeof Schema.Number>;
+            discountPercent: Schema.optional<typeof Schema.Number>;
+            creditCents: Schema.optional<typeof Schema.Number>;
+        }>>;
+        doubleReward: Schema.optional<typeof Schema.Boolean>;
+        minimumDaysBeforeReward: Schema.optional<typeof Schema.Number>;
+    }>>;
+}>;
+export type RedeemRequest = typeof RedeemRequest.Type;
+/**
+ * `POST /referrals/redeem` response. Reward payloads stay as open records —
+ * the concrete shape depends on the reward type and per-app conventions.
+ */
+export declare const RedeemResponse: Schema.Struct<{
+    success: typeof Schema.Boolean;
+    rewardType: typeof Schema.String;
+    referredReward: Schema.optional<Schema.Record$<typeof Schema.String, typeof Schema.Unknown>>;
+    referrerReward: Schema.optional<Schema.Record$<typeof Schema.String, typeof Schema.Unknown>>;
+}>;
+export type RedeemResponse = typeof RedeemResponse.Type;
+/**
+ * BaaS-plane leaderboard entry — distinct from the admin / org-scoped
+ * `LeaderboardEntry` in `organization-referrals`. Display names are masked
+ * server-side for privacy; `userId` is nullable for anonymous submissions.
+ */
+export declare const ReferralLeaderboardEntry: Schema.Struct<{
+    rank: typeof Schema.Number;
+    userId: Schema.NullOr<typeof Schema.String>;
+    displayName: typeof Schema.String;
+    avatarUrl: Schema.NullOr<typeof Schema.String>;
+    value: typeof Schema.Number;
+    isCurrentUser: typeof Schema.Boolean;
+    metadata: Schema.optional<Schema.Record$<typeof Schema.String, typeof Schema.Unknown>>;
+    submittedAt: typeof Schema.String;
+}>;
+export type ReferralLeaderboardEntry = typeof ReferralLeaderboardEntry.Type;
+/** `GET /referrals/leaderboard` response. */
+export declare const ReferralLeaderboardResponse: Schema.Struct<{
+    period: Schema.Literal<["all", "month", "week"]>;
+    entries: Schema.Array$<Schema.Struct<{
+        rank: typeof Schema.Number;
+        userId: Schema.NullOr<typeof Schema.String>;
+        displayName: typeof Schema.String;
+        avatarUrl: Schema.NullOr<typeof Schema.String>;
+        value: typeof Schema.Number;
+        isCurrentUser: typeof Schema.Boolean;
+        metadata: Schema.optional<Schema.Record$<typeof Schema.String, typeof Schema.Unknown>>;
+        submittedAt: typeof Schema.String;
+    }>>;
+    currentUserRank: Schema.NullOr<typeof Schema.Number>;
+}>;
+export type ReferralLeaderboardResponse = typeof ReferralLeaderboardResponse.Type;
+//# sourceMappingURL=referrals.d.ts.map

package/dist/schemas/referrals.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"referrals.d.ts","sourceRoot":"","sources":["../../src/schemas/referrals.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAA;AAI/B,mEAAmE;AACnE,eAAO,MAAM,kBAAkB,qDAAoD,CAAA;AACnF,MAAM,MAAM,kBAAkB,GAAG,OAAO,kBAAkB,CAAC,IAAI,CAAA;AAE/D,mEAAmE;AACnE,eAAO,MAAM,yBAAyB,0CAAyC,CAAA;AAC/E,MAAM,MAAM,yBAAyB,GAAG,OAAO,yBAAyB,CAAC,IAAI,CAAA;AAE7E;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,mEAAkE,CAAA;AACjG,MAAM,MAAM,kBAAkB,GAAG,OAAO,kBAAkB,CAAC,IAAI,CAAA;AAI/D,iEAAiE;AACjE,eAAO,MAAM,oBAAoB;;;;;;EAM/B,CAAA;AACF,MAAM,MAAM,oBAAoB,GAAG,OAAO,oBAAoB,CAAC,IAAI,CAAA;AAEnE;;;;GAIG;AACH,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;;;;EAKjC,CAAA;AACF,MAAM,MAAM,sBAAsB,GAAG,OAAO,sBAAsB,CAAC,IAAI,CAAA;AAIvE,+EAA+E;AAC/E,eAAO,MAAM,eAAe;;;EAG1B,CAAA;AACF,MAAM,MAAM,eAAe,GAAG,OAAO,eAAe,CAAC,IAAI,CAAA;AAEzD,qEAAqE;AACrE,eAAO,MAAM,sBAAsB;;;;;EAKjC,CAAA;AACF,MAAM,MAAM,sBAAsB,GAAG,OAAO,sBAAsB,CAAC,IAAI,CAAA;AAEvE,oEAAoE;AACpE,eAAO,MAAM,gBAAgB;;;;EAI3B,CAAA;AACF,MAAM,MAAM,gBAAgB,GAAG,OAAO,gBAAgB,CAAC,IAAI,CAAA;AAI3D,6CAA6C;AAC7C,eAAO,MAAM,aAAa;;;;;;;;;;;;;;;;;;;;EAGxB,CAAA;AACF,MAAM,MAAM,aAAa,GAAG,OAAO,aAAa,CAAC,IAAI,CAAA;AAErD;;;GAGG;AACH,eAAO,MAAM,cAAc;;;;;EAKzB,CAAA;AACF,MAAM,MAAM,cAAc,GAAG,OAAO,cAAc,CAAC,IAAI,CAAA;AAIvD;;;;GAIG;AACH,eAAO,MAAM,wBAAwB;;;;;;;;;EASnC,CAAA;AACF,MAAM,MAAM,wBAAwB,GAAG,OAAO,wBAAwB,CAAC,IAAI,CAAA;AAE3E,6CAA6C;AAC7C,eAAO,MAAM,2BAA2B;;;;;;;;;;;;;EAItC,CAAA;AACF,MAAM,MAAM,2BAA2B,GAAG,OAAO,2BAA2B,CAAC,IAAI,CAAA"}

package/dist/schemas/referrals.js

@@ -0,0 +1,102 @@
+/**
+ * Referrals — BaaS-plane schemas for the customer-facing referral runtime.
+ * Mirrors the wire shapes served by the deployed-app runtime at
+ * `/referrals/code`, `/referrals/code/regenerate`, `/referrals/stats`,
+ * `/referrals/redeem`, `/referrals/leaderboard` (see
+ * `apps/runtime/src/server/runtime/routes/referrals.ts`).
+ *
+ * Distinct from:
+ *   • `referrals-admin` — super-admin cross-project view
+ *   • `organization-referrals` — Console org read-only program view
+ *
+ * These endpoints are consumed by deployed applications via `@sylphx/sdk`.
+ */
+import { Schema } from 'effect';
+// ── Shared enums ───────────────────────────────────────────────────────────
+/** Runtime status a referral code can report back to end users. */
+export const ReferralCodeStatus = Schema.Literal('pending', 'completed', 'expired');
+/** Leaderboard window reported by `GET /referrals/leaderboard`. */
+export const ReferralLeaderboardPeriod = Schema.Literal('all', 'month', 'week');
+/**
+ * Runtime reward types. Mirrors the contract at `referrals-admin` but kept
+ * as its own declaration so BaaS-plane consumers needn't pull the admin
+ * namespace transitively.
+ */
+export const ReferralRewardKind = Schema.Literal('points', 'premium_trial', 'discount', 'credit');
+// ── Reward configuration ───────────────────────────────────────────────────
+/** Reward for one side (referrer or referee) of a redemption. */
+export const ReferralRewardConfig = Schema.Struct({
+    type: ReferralRewardKind,
+    points: Schema.optional(Schema.Number),
+    days: Schema.optional(Schema.Number),
+    discountPercent: Schema.optional(Schema.Number),
+    creditCents: Schema.optional(Schema.Number),
+});
+/**
+ * Inline defaults passed with a redemption request. Console-configured
+ * rewards win if present; otherwise these defaults are auto-discovered
+ * (ADR-004).
+ */
+export const ReferralRewardDefaults = Schema.Struct({
+    referrerReward: Schema.optional(ReferralRewardConfig),
+    refereeReward: Schema.optional(ReferralRewardConfig),
+    doubleReward: Schema.optional(Schema.Boolean),
+    minimumDaysBeforeReward: Schema.optional(Schema.Number),
+});
+// ── Code / stats responses ─────────────────────────────────────────────────
+/** `GET /referrals/code` — returns (or creates) the caller's referral code. */
+export const GetCodeResponse = Schema.Struct({
+    code: Schema.String,
+    status: ReferralCodeStatus,
+});
+/** `POST /referrals/code/regenerate` — rotates the caller's code. */
+export const RegenerateCodeResponse = Schema.Struct({
+    code: Schema.String,
+    totalReferrals: Schema.Number,
+    completedReferrals: Schema.Number,
+    pendingReferrals: Schema.Number,
+});
+/** `GET /referrals/stats` — caller's personal referral counters. */
+export const GetStatsResponse = Schema.Struct({
+    totalReferrals: Schema.Number,
+    completedReferrals: Schema.Number,
+    pendingReferrals: Schema.Number,
+});
+// ── Redeem ─────────────────────────────────────────────────────────────────
+/** `POST /referrals/redeem` request body. */
+export const RedeemRequest = Schema.Struct({
+    code: Schema.String,
+    defaults: Schema.optional(ReferralRewardDefaults),
+});
+/**
+ * `POST /referrals/redeem` response. Reward payloads stay as open records —
+ * the concrete shape depends on the reward type and per-app conventions.
+ */
+export const RedeemResponse = Schema.Struct({
+    success: Schema.Boolean,
+    rewardType: Schema.String,
+    referredReward: Schema.optional(Schema.Record({ key: Schema.String, value: Schema.Unknown })),
+    referrerReward: Schema.optional(Schema.Record({ key: Schema.String, value: Schema.Unknown })),
+});
+// ── Leaderboard ────────────────────────────────────────────────────────────
+/**
+ * BaaS-plane leaderboard entry — distinct from the admin / org-scoped
+ * `LeaderboardEntry` in `organization-referrals`. Display names are masked
+ * server-side for privacy; `userId` is nullable for anonymous submissions.
+ */
+export const ReferralLeaderboardEntry = Schema.Struct({
+    rank: Schema.Number,
+    userId: Schema.NullOr(Schema.String),
+    displayName: Schema.String,
+    avatarUrl: Schema.NullOr(Schema.String),
+    value: Schema.Number,
+    isCurrentUser: Schema.Boolean,
+    metadata: Schema.optional(Schema.Record({ key: Schema.String, value: Schema.Unknown })),
+    submittedAt: Schema.String,
+});
+/** `GET /referrals/leaderboard` response. */
+export const ReferralLeaderboardResponse = Schema.Struct({
+    period: ReferralLeaderboardPeriod,
+    entries: Schema.Array(ReferralLeaderboardEntry),
+    currentUserRank: Schema.NullOr(Schema.Number),
+});

package/dist/schemas/refresh.d.ts

@@ -0,0 +1,29 @@
+/**
+ * OAuth refresh — schemas for ADR-059 §1.1 refresh/logout.
+ * Mirrors `routes/refresh.ts`.
+ *
+ * Plane: `management`. Endpoints are PUBLIC (no auth) — they authenticate
+ * via the presented refresh token itself.
+ */
+import { Schema } from 'effect';
+export declare const RefreshTokenInput: Schema.Struct<{
+    refresh_token: typeof Schema.String;
+}>;
+export type RefreshTokenInput = typeof RefreshTokenInput.Type;
+export declare const RefreshTokenResult: Schema.Struct<{
+    access_token: typeof Schema.String;
+    refresh_token: typeof Schema.String;
+    token_type: Schema.Literal<["Bearer"]>;
+    expires_in: typeof Schema.Number;
+    refresh_expires_at: typeof Schema.String;
+}>;
+export type RefreshTokenResult = typeof RefreshTokenResult.Type;
+export declare const LogoutInput: Schema.Struct<{
+    refresh_token: typeof Schema.String;
+}>;
+export type LogoutInput = typeof LogoutInput.Type;
+export declare const LogoutResult: Schema.Struct<{
+    revoked: typeof Schema.Boolean;
+}>;
+export type LogoutResult = typeof LogoutResult.Type;
+//# sourceMappingURL=refresh.d.ts.map

package/dist/schemas/refresh.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"refresh.d.ts","sourceRoot":"","sources":["../../src/schemas/refresh.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAA;AAE/B,eAAO,MAAM,iBAAiB;;EAAkD,CAAA;AAChF,MAAM,MAAM,iBAAiB,GAAG,OAAO,iBAAiB,CAAC,IAAI,CAAA;AAE7D,eAAO,MAAM,kBAAkB;;;;;;EAM7B,CAAA;AACF,MAAM,MAAM,kBAAkB,GAAG,OAAO,kBAAkB,CAAC,IAAI,CAAA;AAE/D,eAAO,MAAM,WAAW;;EAAkD,CAAA;AAC1E,MAAM,MAAM,WAAW,GAAG,OAAO,WAAW,CAAC,IAAI,CAAA;AACjD,eAAO,MAAM,YAAY;;EAA6C,CAAA;AACtE,MAAM,MAAM,YAAY,GAAG,OAAO,YAAY,CAAC,IAAI,CAAA"}