@spacefast/common 0.0.2

package/dist/contracts/teams.d.ts

@@ -0,0 +1,233 @@
+import { z } from "zod";
+export declare const TEAM_ROLE_VALUES: readonly ["owner", "admin", "member"];
+export declare const PLAN_FEATURE_VALUES: readonly ["version-diagnostics"];
+export declare const teamMemberRole: z.ZodEnum<{
+    owner: "owner";
+    admin: "admin";
+    member: "member";
+}>;
+export declare const teamInvitationCreateSchema: z.ZodObject<{
+    email: z.ZodString;
+    role: z.ZodDefault<z.ZodEnum<{
+        owner: "owner";
+        admin: "admin";
+        member: "member";
+    }>>;
+}, z.core.$strip>;
+export declare const teamMemberListQuerySchema: z.ZodObject<{
+    limit: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    cursor: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const teamInvitationListQuerySchema: z.ZodObject<{
+    limit: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    cursor: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const teamListQuerySchema: z.ZodObject<{
+    limit: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    cursor: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const teamSpaceListQuerySchema: z.ZodObject<{
+    limit: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    cursor: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const TeamInvitationSchema: z.ZodObject<{
+    id: z.ZodString;
+    teamId: z.ZodString;
+    email: z.ZodString;
+    role: z.ZodEnum<{
+        owner: "owner";
+        admin: "admin";
+        member: "member";
+    }>;
+    status: z.ZodString;
+    expiresAt: z.ZodString;
+    createdAt: z.ZodString;
+}, z.core.$strip>;
+export declare const teamPlanCode: z.ZodEnum<{
+    personal: "personal";
+    work: "work";
+    enterprise: "enterprise";
+    internal: "internal";
+    free: "free";
+}>;
+export declare const TeamSummarySchema: z.ZodObject<{
+    id: z.ZodString;
+    tenantId: z.ZodString;
+    name: z.ZodString;
+    slug: z.ZodString;
+    role: z.ZodEnum<{
+        owner: "owner";
+        admin: "admin";
+        member: "member";
+    }>;
+    plan: z.ZodEnum<{
+        personal: "personal";
+        work: "work";
+        enterprise: "enterprise";
+        internal: "internal";
+        free: "free";
+    }>;
+    defaultDataLocation: z.ZodString;
+    createdAt: z.ZodString;
+    updatedAt: z.ZodString;
+}, z.core.$strip>;
+export declare const TeamDetailSchema: z.ZodObject<{
+    id: z.ZodString;
+    tenantId: z.ZodString;
+    name: z.ZodString;
+    slug: z.ZodString;
+    role: z.ZodEnum<{
+        owner: "owner";
+        admin: "admin";
+        member: "member";
+    }>;
+    plan: z.ZodEnum<{
+        personal: "personal";
+        work: "work";
+        enterprise: "enterprise";
+        internal: "internal";
+        free: "free";
+    }>;
+    defaultDataLocation: z.ZodString;
+    createdAt: z.ZodString;
+    updatedAt: z.ZodString;
+    logo: z.ZodNullable<z.ZodString>;
+    metadata: z.ZodNullable<z.ZodString>;
+    stripeCustomerId: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+export declare const teamListResponseSchema: z.ZodObject<{
+    data: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        tenantId: z.ZodString;
+        name: z.ZodString;
+        slug: z.ZodString;
+        role: z.ZodEnum<{
+            owner: "owner";
+            admin: "admin";
+            member: "member";
+        }>;
+        plan: z.ZodEnum<{
+            personal: "personal";
+            work: "work";
+            enterprise: "enterprise";
+            internal: "internal";
+            free: "free";
+        }>;
+        defaultDataLocation: z.ZodString;
+        createdAt: z.ZodString;
+        updatedAt: z.ZodString;
+    }, z.core.$strip>>;
+    pagination: z.ZodObject<{
+        nextCursor: z.ZodNullable<z.ZodString>;
+        hasMore: z.ZodBoolean;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export declare const teamMemberListResponseSchema: z.ZodObject<{
+    data: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        teamId: z.ZodString;
+        userId: z.ZodString;
+        role: z.ZodEnum<{
+            owner: "owner";
+            admin: "admin";
+            member: "member";
+        }>;
+        createdAt: z.ZodString;
+        user: z.ZodNullable<z.ZodObject<{
+            id: z.ZodString;
+            name: z.ZodString;
+            email: z.ZodString;
+            image: z.ZodNullable<z.ZodString>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+    pagination: z.ZodObject<{
+        nextCursor: z.ZodNullable<z.ZodString>;
+        hasMore: z.ZodBoolean;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export declare const teamJoinResponseSchema: z.ZodObject<{
+    data: z.ZodObject<{
+        teamId: z.ZodString;
+        userId: z.ZodString;
+        role: z.ZodLiteral<"member">;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export declare const teamInvitationListResponseSchema: z.ZodObject<{
+    data: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        teamId: z.ZodString;
+        email: z.ZodString;
+        role: z.ZodEnum<{
+            owner: "owner";
+            admin: "admin";
+            member: "member";
+        }>;
+        status: z.ZodString;
+        expiresAt: z.ZodString;
+        createdAt: z.ZodString;
+    }, z.core.$strip>>;
+    pagination: z.ZodObject<{
+        nextCursor: z.ZodNullable<z.ZodString>;
+        hasMore: z.ZodBoolean;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export declare const teamDataLocationSchema: z.ZodString;
+export declare const teamSettingsUpdateSchema: z.ZodObject<{
+    defaultDataLocation: z.ZodString;
+}, z.core.$strip>;
+export declare const teamSettingsResponseSchema: z.ZodObject<{
+    teamId: z.ZodString;
+    defaultDataLocation: z.ZodString;
+    regionOptions: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        label: z.ZodString;
+    }, z.core.$strip>>;
+    wpCloudCapabilities: z.ZodObject<{
+        status: z.ZodEnum<{
+            failed: "failed";
+            running: "running";
+            ready: "ready";
+            idle: "idle";
+        }>;
+        degraded: z.ZodBoolean;
+        lastSyncedAt: z.ZodNullable<z.ZodString>;
+        lastError: z.ZodNullable<z.ZodString>;
+        regionCount: z.ZodNumber;
+        phpVersionCount: z.ZodNumber;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export declare const teamUsageResponseSchema: z.ZodObject<{
+    teamId: z.ZodString;
+    usage: z.ZodObject<{
+        spaces: z.ZodNumber;
+        domains: z.ZodNumber;
+        members: z.ZodNumber;
+        storageBytes: z.ZodNumber;
+        storageQuotaBytes: z.ZodUnion<readonly [z.ZodNumber, z.ZodLiteral<"unlimited">]>;
+        storageOverageBytes: z.ZodNumber;
+        storageCalculatedAt: z.ZodNullable<z.ZodString>;
+        storageOverQuotaSince: z.ZodNullable<z.ZodString>;
+        storageWarningSentAt: z.ZodNullable<z.ZodString>;
+        buildsDeploysThisMonth: z.ZodNumber;
+        buildsDeploysMonthly: z.ZodUnion<readonly [z.ZodNumber, z.ZodLiteral<"unlimited">]>;
+        meterStartedAt: z.ZodNullable<z.ZodString>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export declare const teamInvitationPreviewSchema: z.ZodObject<{
+    id: z.ZodString;
+    teamName: z.ZodString;
+    invitedEmail: z.ZodString;
+    status: z.ZodEnum<{
+        closed: "closed";
+        expired: "expired";
+        pending: "pending";
+    }>;
+    expiresAt: z.ZodString;
+}, z.core.$strip>;
+export declare const teamUpdateSchema: z.ZodObject<{
+    name: z.ZodOptional<z.ZodString>;
+    slug: z.ZodOptional<z.ZodString>;
+    logo: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    metadata: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    defaultDataLocation: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;

package/dist/contracts/teams.js

@@ -0,0 +1,174 @@
+import { z } from "zod";
+import { CursorPaginationSchema, cursorListQuerySchema } from "./common.js";
+import { planCodeSchema, planLimitValueSchema } from "./features.js";
+export const TEAM_ROLE_VALUES = ["owner", "admin", "member"];
+export const PLAN_FEATURE_VALUES = ["version-diagnostics"];
+export const teamMemberRole = z.enum(TEAM_ROLE_VALUES);
+export const teamInvitationCreateSchema = z.object({
+    email: z.string().trim().email().toLowerCase(),
+    role: teamMemberRole.default("member"),
+});
+export const teamMemberListQuerySchema = cursorListQuerySchema;
+export const teamInvitationListQuerySchema = cursorListQuerySchema;
+export const teamListQuerySchema = cursorListQuerySchema;
+export const teamSpaceListQuerySchema = cursorListQuerySchema;
+const TeamMemberUserSchema = z.object({
+    id: z.string(),
+    name: z.string(),
+    email: z.string().email(),
+    image: z.string().nullable(),
+});
+const TeamMemberSchema = z.object({
+    id: z.string(),
+    teamId: z.string(),
+    userId: z.string(),
+    role: teamMemberRole,
+    createdAt: z.string().datetime(),
+    user: TeamMemberUserSchema.nullable(),
+});
+export const TeamInvitationSchema = z.object({
+    id: z.string(),
+    teamId: z.string(),
+    email: z.string().email(),
+    role: teamMemberRole,
+    status: z.string(),
+    expiresAt: z.string().datetime(),
+    createdAt: z.string().datetime(),
+});
+// Team (internal-docs/platform.md "Team"): Better Auth team in the main
+// tenant, carrying the resolved plan and default data location.
+export const teamPlanCode = planCodeSchema;
+export const TeamSummarySchema = z.object({
+    id: z.string().describe("Team id (the Better Auth team id in the main tenant)."),
+    tenantId: z.string().describe("Owning tenant; ten_main for self-serve teams."),
+    name: z.string().describe("Display name of the team."),
+    slug: z.string().describe("URL-safe team slug, unique per tenant."),
+    role: teamMemberRole.describe("Requesting member's role; member for non-session credentials."),
+    plan: teamPlanCode.describe("Resolved plan code from the active subscription."),
+    defaultDataLocation: z
+        .string()
+        .describe('Default placement region for new spaces; "auto" lets placement decide.'),
+    createdAt: z.string().datetime(),
+    updatedAt: z.string().datetime(),
+});
+export const TeamDetailSchema = TeamSummarySchema.extend({
+    logo: z.string().nullable().describe("Optional team logo URL."),
+    metadata: z.string().nullable().describe("Opaque team metadata stored by the client."),
+    stripeCustomerId: z
+        .string()
+        .nullable()
+        .describe("Stripe customer id linked to this team, when billing has been initialized."),
+});
+export const teamListResponseSchema = z.object({
+    data: z.array(TeamSummarySchema),
+    pagination: CursorPaginationSchema,
+});
+export const teamMemberListResponseSchema = z.object({
+    data: z.array(TeamMemberSchema),
+    pagination: CursorPaginationSchema,
+});
+export const teamJoinResponseSchema = z.object({
+    data: z.object({
+        teamId: z.string(),
+        userId: z.string(),
+        role: z.literal("member"),
+    }),
+});
+export const teamInvitationListResponseSchema = z.object({
+    data: z.array(TeamInvitationSchema),
+    pagination: CursorPaginationSchema,
+});
+// Team activity is served by `GET /v1/teams/{teamId}/activity`, a facade over
+// the one activity store using the ActivityEvent contract (contracts/activity.ts).
+// `defaultDataLocation` is the spec Team field: "auto" lets placement decide,
+// any other value must be an available placement region id.
+export const teamDataLocationSchema = z
+    .string()
+    .trim()
+    .min(1)
+    .max(64)
+    .describe('Default placement region for new spaces; "auto" lets placement decide.');
+export const teamSettingsUpdateSchema = z.object({
+    defaultDataLocation: teamDataLocationSchema,
+});
+// Served by `GET /v1/teams/{teamId}/settings` (and echoed by the PATCH):
+// the default data location plus the placement options it may take.
+export const teamSettingsResponseSchema = z.object({
+    teamId: z.string().describe("Team the settings belong to."),
+    defaultDataLocation: teamDataLocationSchema,
+    regionOptions: z
+        .array(z.object({
+        id: z.string().describe("Placement region id."),
+        label: z.string().describe("Human-readable region label."),
+    }))
+        .describe("Placement regions currently available for new spaces."),
+    wpCloudCapabilities: z
+        .object({
+        status: z
+            .enum(["idle", "running", "ready", "failed"])
+            .describe("State of the provider capability sync."),
+        degraded: z.boolean().describe("Whether the last sync finished with an error."),
+        lastSyncedAt: z.string().nullable().describe("When capabilities last synced."),
+        lastError: z.string().nullable().describe("Last sync error, if any."),
+        regionCount: z.number().int().describe("Known placement regions."),
+        phpVersionCount: z.number().int().describe("Known runtime PHP versions."),
+    })
+        .describe("Provider capability sync status backing the region options."),
+});
+// Served by `GET /v1/teams/{teamId}/usage`: counts and metered usage against
+// the named plan limits.
+export const teamUsageResponseSchema = z.object({
+    teamId: z.string().describe("Team the usage was metered for."),
+    usage: z
+        .object({
+        spaces: z.number().int().describe("Live spaces in the team."),
+        domains: z.number().int().describe("External domain groups counted against the plan."),
+        members: z.number().int().describe("Team members."),
+        storageBytes: z.number().describe("Stored bytes across the team's spaces."),
+        storageQuotaBytes: z
+            .union([z.number(), z.literal("unlimited")])
+            .describe('Plan storage quota; "unlimited" when unbounded.'),
+        storageOverageBytes: z.number().describe("Bytes over the plan storage quota."),
+        storageCalculatedAt: z.string().nullable().describe("When storage was last accounted."),
+        storageOverQuotaSince: z
+            .string()
+            .nullable()
+            .describe("When the team first went over its storage quota."),
+        storageWarningSentAt: z.string().nullable().describe("When the over-quota warning went out."),
+        buildsDeploysThisMonth: z
+            .number()
+            .int()
+            .describe("Publishes (user pushes and CI builds pooled) this month."),
+        buildsDeploysMonthly: planLimitValueSchema.describe("Monthly publish limit for the plan."),
+        meterStartedAt: z.string().nullable().describe("Start of the current metering month."),
+    })
+        .describe("Usage counters against the named plan limits."),
+});
+// Served by `GET /v1/teams/invitations/{invitationId}/preview`: the unauthenticated
+// invite landing view (email is masked, never the full address).
+export const teamInvitationPreviewSchema = z.object({
+    id: z.string().describe("Invitation id."),
+    teamName: z.string().describe("Inviting team's display name."),
+    invitedEmail: z.string().describe("Masked invited email address."),
+    status: z.enum(["pending", "expired", "closed"]).describe("Whether the invite can be accepted."),
+    expiresAt: z.string().describe("When the invitation expires."),
+});
+export const teamUpdateSchema = z
+    .object({
+    name: z.string().trim().min(1).max(255).optional(),
+    slug: z
+        .string()
+        .trim()
+        .min(1)
+        .max(255)
+        .regex(/^[a-z0-9][a-z0-9-]*[a-z0-9]$|^[a-z0-9]$/, {
+        message: "Team slugs must contain lowercase letters, numbers, and hyphens.",
+    })
+        .optional(),
+    logo: z.string().trim().max(2048).nullable().optional(),
+    metadata: z.string().nullable().optional(),
+    defaultDataLocation: teamDataLocationSchema.optional(),
+})
+    .refine((value) => Object.keys(value).length > 0, {
+    message: "At least one team field is required.",
+});

package/dist/contracts/telemetry.d.ts

@@ -0,0 +1,2 @@
+export { EVENT_BODY_CAP_BYTES as TELEMETRY_BODY_CAP_BYTES, EVENT_MAX_EVENTS_PER_REQUEST as TELEMETRY_MAX_EVENTS_PER_REQUEST, eventAcceptedSchema as telemetryAcceptedSchema, eventIngestSchema as telemetryIngestSchema, eventPayloadSchema as telemetryEventSchema, } from "./events.js";
+export type { EventIngest as TelemetryIngest, EventPayload as TelemetryEvent } from "./events.js";

package/dist/contracts/telemetry.js

@@ -0,0 +1 @@
+export { EVENT_BODY_CAP_BYTES as TELEMETRY_BODY_CAP_BYTES, EVENT_MAX_EVENTS_PER_REQUEST as TELEMETRY_MAX_EVENTS_PER_REQUEST, eventAcceptedSchema as telemetryAcceptedSchema, eventIngestSchema as telemetryIngestSchema, eventPayloadSchema as telemetryEventSchema, } from "./events.js";

package/dist/contracts/transfers.d.ts

@@ -0,0 +1,105 @@
+import { z } from "zod";
+export declare const principalIdSchema: z.ZodString;
+export declare const transferPrincipalInputSchema: z.ZodObject<{
+    principalType: z.ZodEnum<{
+        external: "external";
+        team: "team";
+    }>;
+    principalId: z.ZodString;
+}, z.core.$strip>;
+export declare const transferPrincipalSchema: z.ZodObject<{
+    principalType: z.ZodEnum<{
+        external: "external";
+        team: "team";
+    }>;
+    principalId: z.ZodString;
+    tenantId: z.ZodString;
+}, z.core.$strip>;
+export declare const spaceTransferCreateSchema: z.ZodObject<{
+    to: z.ZodObject<{
+        principalType: z.ZodEnum<{
+            external: "external";
+            team: "team";
+        }>;
+        principalId: z.ZodString;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export declare const spaceTransferSchema: z.ZodObject<{
+    id: z.ZodString;
+    spaceId: z.ZodString;
+    from: z.ZodObject<{
+        principalType: z.ZodEnum<{
+            external: "external";
+            team: "team";
+        }>;
+        principalId: z.ZodString;
+        tenantId: z.ZodString;
+    }, z.core.$strip>;
+    to: z.ZodObject<{
+        principalType: z.ZodEnum<{
+            external: "external";
+            team: "team";
+        }>;
+        principalId: z.ZodString;
+        tenantId: z.ZodString;
+    }, z.core.$strip>;
+    status: z.ZodEnum<{
+        completed: "completed";
+        canceled: "canceled";
+        expired: "expired";
+        moving: "moving";
+        pending_confirmation: "pending_confirmation";
+        confirming_domains: "confirming_domains";
+    }>;
+    requiredActions: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        type: z.ZodLiteral<"dns">;
+        instructions: z.ZodArray<z.ZodObject<{
+            type: z.ZodEnum<{
+                A: "A";
+                AAAA: "AAAA";
+                CNAME: "CNAME";
+                TXT: "TXT";
+                ALIAS: "ALIAS";
+            }>;
+            name: z.ZodString;
+            value: z.ZodString;
+            ttl: z.ZodOptional<z.ZodNumber>;
+            purpose: z.ZodEnum<{
+                verification: "verification";
+                routing: "routing";
+                ssl: "ssl";
+            }>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"confirm_move">;
+        conflictId: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"verify_domain">;
+        domainId: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"renew">;
+        domainId: z.ZodString;
+    }, z.core.$strip>], "type">>;
+    diagnostics: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        code: z.ZodString;
+        severity: z.ZodEnum<{
+            info: "info";
+            warning: "warning";
+            error: "error";
+        }>;
+        message: z.ZodString;
+        path: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        provider: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
+            wpcloud: "wpcloud";
+            dns: "dns";
+            registrar: "registrar";
+            runtime: "runtime";
+        }>>>;
+        details: z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+        fix: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        retryable: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
+    }, z.core.$strip>>>;
+    expiresAt: z.ZodString;
+    createdAt: z.ZodString;
+    updatedAt: z.ZodString;
+}, z.core.$strip>;

package/dist/contracts/transfers.js

@@ -0,0 +1,48 @@
+import { z } from "zod";
+import { baseDiagnosticSchema, requiredActionsSchema } from "./common.js";
+import { spaceTransferStatus } from "./enums.js";
+// Tenant-local external principal id grammar (internal-docs/platform.md
+// "Principal"): 1-256 chars, no whitespace, no `/` or `\`, no
+// control/non-printable characters. Team principal ids are Better Auth team
+// ids and trivially satisfy the same grammar.
+export const principalIdSchema = z
+    .string()
+    .min(1)
+    .max(256)
+    .regex(/^[^\s/\\]+$/)
+    .refine((value) => [...value].every((char) => {
+    const code = char.codePointAt(0) ?? 0;
+    return code >= 32 && code !== 127;
+}))
+    .describe("Tenant-local principal id: a team id, or the integrator's own external customer id.");
+// Request `to` omits tenantId: transfers are tenant-local and the tenant is
+// inferred from the space (internal-docs/platform.md "Transfer semantics").
+export const transferPrincipalInputSchema = z.object({
+    principalType: z
+        .enum(["team", "external"])
+        .describe("Receiving principal kind: a first-party team or a host-managed external principal."),
+    principalId: principalIdSchema,
+});
+// Responses carry the full canonical PrincipalRef shape.
+export const transferPrincipalSchema = transferPrincipalInputSchema.extend({
+    tenantId: z.string().min(1).describe("Tenant both transfer parties live in."),
+});
+export const spaceTransferCreateSchema = z.object({
+    to: transferPrincipalInputSchema.describe("Receiving principal. Must live in the space's tenant; cross-tenant transfers are unsupported."),
+});
+export const spaceTransferSchema = z.object({
+    id: z.string().describe("SpaceTransfer id (`trf_`)."),
+    spaceId: z.string().describe("Space being transferred."),
+    from: transferPrincipalSchema.describe("Current owner. Keeps full control, serving, and billing attribution until `completed`."),
+    to: transferPrincipalSchema.describe("Receiving principal; confirm is a to-side action."),
+    status: spaceTransferStatus.describe("Transfer state. `confirming_domains` waits on re-confirmation of bound domains; a failed move reverts to `pending_confirmation` with a diagnostic (there is no failed state)."),
+    // Domain confirmations the receiving principal must complete before the move.
+    requiredActions: requiredActionsSchema,
+    diagnostics: z.array(baseDiagnosticSchema).default([]),
+    expiresAt: z
+        .string()
+        .datetime()
+        .describe("Pending transfers expire after this stamp (default 7 days)."),
+    createdAt: z.string().datetime(),
+    updatedAt: z.string().datetime(),
+});