@stacksjs/ts-analytics 0.1.6

package/src/lib/membership.ts

@@ -0,0 +1,98 @@
+/**
+ * Project membership — the User <-> Project (site) relationship.
+ *
+ * One user can belong to many projects, each with a role. Stored as a pair of
+ * mirrored items so both directions are a single-partition query:
+ *   USER#{userId}  / MEMBERSHIP#SITE#{siteId}   -> a user's projects
+ *   SITE#{siteId}  / MEMBER#{userId}            -> a project's members
+ *
+ * getMembership() is the O(1) lookup the authz layer uses on every request.
+ */
+import { dynamodb, TABLE_NAME, marshall, unmarshall } from './dynamodb'
+
+export type Role = 'owner' | 'admin' | 'editor' | 'viewer'
+
+const RANK: Record<Role, number> = { viewer: 1, editor: 2, admin: 3, owner: 4 }
+
+/** True if `role` is at least as privileged as `min`. */
+export function roleAtLeast(role: Role | null | undefined, min: Role): boolean {
+  return !!role && RANK[role] >= RANK[min]
+}
+
+export async function addMembership(userId: string, siteId: string, role: Role): Promise<void> {
+  const addedAt = new Date().toISOString()
+  await dynamodb.putItem({
+    TableName: TABLE_NAME,
+    Item: marshall({ pk: `USER#${userId}`, sk: `MEMBERSHIP#SITE#${siteId}`, userId, siteId, role, addedAt }),
+  })
+  await dynamodb.putItem({
+    TableName: TABLE_NAME,
+    Item: marshall({ pk: `SITE#${siteId}`, sk: `MEMBER#${userId}`, userId, siteId, role, addedAt }),
+  })
+}
+
+export async function removeMembership(userId: string, siteId: string): Promise<void> {
+  await dynamodb.deleteItem({ TableName: TABLE_NAME, Key: { pk: { S: `USER#${userId}` }, sk: { S: `MEMBERSHIP#SITE#${siteId}` } } })
+  await dynamodb.deleteItem({ TableName: TABLE_NAME, Key: { pk: { S: `SITE#${siteId}` }, sk: { S: `MEMBER#${userId}` } } })
+}
+
+/** The caller's role on a project, or null if they're not a member. */
+export async function getMembership(userId: string, siteId: string): Promise<Role | null> {
+  const r = await dynamodb.getItem({
+    TableName: TABLE_NAME,
+    Key: { pk: { S: `USER#${userId}` }, sk: { S: `MEMBERSHIP#SITE#${siteId}` } },
+  })
+  if (!r.Item) return null
+  return (unmarshall(r.Item).role as Role) || null
+}
+
+export async function getUserMemberships(userId: string): Promise<{ siteId: string; role: Role }[]> {
+  const r = await dynamodb.query({
+    TableName: TABLE_NAME,
+    KeyConditionExpression: 'pk = :pk AND begins_with(sk, :sk)',
+    ExpressionAttributeValues: { ':pk': { S: `USER#${userId}` }, ':sk': { S: 'MEMBERSHIP#SITE#' } },
+  }) as { Items?: any[] }
+  return (r.Items || []).map(unmarshall).map((m: any) => ({ siteId: m.siteId, role: m.role as Role }))
+}
+
+// ---- Pending invites (for emails without an account yet) -------------------
+// Keyed by email so they can be found + auto-accepted when the person signs up:
+//   INVITE#{email} / SITE#{siteId} -> role
+
+export async function addPendingInvite(email: string, siteId: string, role: Role): Promise<void> {
+  await dynamodb.putItem({
+    TableName: TABLE_NAME,
+    Item: marshall({ pk: `INVITE#${email.toLowerCase()}`, sk: `SITE#${siteId}`, email: email.toLowerCase(), siteId, role, invitedAt: new Date().toISOString() }),
+  })
+}
+
+export async function getPendingInvites(email: string): Promise<{ siteId: string; role: Role }[]> {
+  const r = await dynamodb.query({
+    TableName: TABLE_NAME,
+    KeyConditionExpression: 'pk = :pk',
+    ExpressionAttributeValues: { ':pk': { S: `INVITE#${email.toLowerCase()}` } },
+  }) as { Items?: any[] }
+  return (r.Items || []).map(unmarshall).map((i: any) => ({ siteId: i.siteId, role: i.role as Role }))
+}
+
+/** Convert all pending invites for an email into real memberships. Returns count. */
+export async function acceptInvites(userId: string, email: string): Promise<number> {
+  const invites = await getPendingInvites(email)
+  for (const inv of invites) {
+    await addMembership(userId, inv.siteId, inv.role)
+    await dynamodb.deleteItem({
+      TableName: TABLE_NAME,
+      Key: { pk: { S: `INVITE#${email.toLowerCase()}` }, sk: { S: `SITE#${inv.siteId}` } },
+    })
+  }
+  return invites.length
+}
+
+export async function getSiteMembers(siteId: string): Promise<{ userId: string; role: Role }[]> {
+  const r = await dynamodb.query({
+    TableName: TABLE_NAME,
+    KeyConditionExpression: 'pk = :pk AND begins_with(sk, :sk)',
+    ExpressionAttributeValues: { ':pk': { S: `SITE#${siteId}` }, ':sk': { S: 'MEMBER#' } },
+  }) as { Items?: any[] }
+  return (r.Items || []).map(unmarshall).map((m: any) => ({ userId: m.userId, role: m.role as Role }))
+}

package/src/lib/plans.ts

@@ -0,0 +1,90 @@
+/**
+ * Account plans & limits (#62) — billing foundation.
+ *
+ * Every account has a plan (USER# record `plan` field, default 'free') with
+ * three limits: projects, monthly events across all owned projects, and max
+ * retention days. 0 means unlimited. Enforcement points:
+ *   - project create  → maxProjects (hard 403)
+ *   - ingest          → monthlyEvents via an atomic per-account month counter
+ *                       (USER#{ownerId} / QUOTA#{YYYY-MM}); fails open
+ *   - retention update → retentionDays clamp
+ * All plans are effectively generous-free until billing exists; the checks and
+ * storage are what this scaffolds.
+ */
+import { dynamodb, TABLE_NAME, unmarshall } from './dynamodb'
+import { monthKey, quotaExceeded } from './quota'
+
+export interface PlanLimits {
+  /** Max owned projects (0 = unlimited). */
+  maxProjects: number
+  /** Max events per calendar month across all owned projects (0 = unlimited). */
+  monthlyEvents: number
+  /** Max data retention in days (0 = unlimited). */
+  retentionDays: number
+}
+
+export const PLANS: Record<string, PlanLimits> = {
+  free: { maxProjects: 25, monthlyEvents: 1_000_000, retentionDays: 365 },
+  pro: { maxProjects: 100, monthlyEvents: 10_000_000, retentionDays: 1095 },
+  unlimited: { maxProjects: 0, monthlyEvents: 0, retentionDays: 0 },
+}
+
+/** Limits for a plan name; unknown/missing plans resolve to free. Pure — unit tested. */
+export function planLimits(plan?: string | null): PlanLimits {
+  return PLANS[plan || 'free'] || PLANS.free
+}
+
+// Plan lookups happen on the ingest hot path → small in-memory cache.
+const planCache = new Map<string, { plan: string, expires: number }>()
+const PLAN_CACHE_TTL = 5 * 60_000
+
+/** The account's plan name (USER# record `plan`, default 'free'). */
+export async function getUserPlan(userId: string): Promise<string> {
+  const hit = planCache.get(userId)
+  if (hit && hit.expires > Date.now())
+    return hit.plan
+  let plan = 'free'
+  try {
+    const res = await dynamodb.getItem({
+      TableName: TABLE_NAME,
+      Key: { pk: { S: `USER#${userId}` }, sk: { S: `USER#${userId}` } },
+    }) as { Item?: Record<string, any> }
+    if (res.Item) {
+      const user = unmarshall(res.Item)
+      if (user.plan && PLANS[user.plan])
+        plan = user.plan
+    }
+  }
+  catch (e) {
+    console.error('Plan lookup failed:', (e as Error).message)
+  }
+  planCache.set(userId, { plan, expires: Date.now() + PLAN_CACHE_TTL })
+  return plan
+}
+
+/**
+ * Atomically count an event against the owner's monthly account quota and
+ * report whether it is still within plan. Fails open on errors; no-op (true)
+ * when the plan is unlimited.
+ */
+export async function accountEventWithinQuota(ownerId: string): Promise<boolean> {
+  const limits = planLimits(await getUserPlan(ownerId))
+  if (limits.monthlyEvents <= 0)
+    return true
+  try {
+    const res = await dynamodb.updateItem({
+      TableName: TABLE_NAME,
+      Key: { pk: { S: `USER#${ownerId}` }, sk: { S: `QUOTA#${monthKey()}` } },
+      UpdateExpression: 'ADD #c :one SET #t = if_not_exists(#t, :ttl)',
+      ExpressionAttributeNames: { '#c': 'count', '#t': 'ttl' },
+      ExpressionAttributeValues: { ':one': { N: '1' }, ':ttl': { N: String(Math.floor(Date.now() / 1000) + 70 * 24 * 3600) } },
+      ReturnValues: 'UPDATED_NEW',
+    }) as { Attributes?: Record<string, unknown> }
+    const count = res.Attributes ? (unmarshall(res.Attributes).count as number) : 0
+    return !quotaExceeded(count, limits.monthlyEvents)
+  }
+  catch (e) {
+    console.error('Account quota check failed:', (e as Error).message)
+    return true
+  }
+}

package/src/lib/quota.ts

@@ -0,0 +1,46 @@
+/**
+ * Per-project monthly event quota for error ingest.
+ *
+ * A coarse cap (separate from the per-key rate limit in lib/rate-limit) that
+ * bounds total events per project per calendar month. Backed by a DynamoDB
+ * counter so it holds across instances. Disabled by default (no quota set).
+ */
+import { dynamodb, TABLE_NAME, unmarshall } from './dynamodb'
+
+/** Monthly event cap per project (env ANALYTICS_MONTHLY_EVENT_QUOTA; 0 = unlimited). */
+export const MONTHLY_EVENT_QUOTA: number = Number(process.env.ANALYTICS_MONTHLY_EVENT_QUOTA) || 0
+
+/** Current month bucket key (YYYY-MM). */
+export function monthKey(d: Date = new Date()): string {
+  return d.toISOString().slice(0, 7)
+}
+
+/** True when the running count has passed the limit (limit <= 0 means unlimited). */
+export function quotaExceeded(count: number, limit: number): boolean {
+  return limit > 0 && count > limit
+}
+
+/**
+ * Atomically increment a project's monthly event counter and report whether it
+ * is still within quota. Fails open (returns true) on errors so a quota glitch
+ * never drops events; a no-op (true) when no quota is configured.
+ */
+export async function recordEventWithinQuota(siteId: string): Promise<boolean> {
+  if (MONTHLY_EVENT_QUOTA <= 0) return true
+  try {
+    const res = await dynamodb.updateItem({
+      TableName: TABLE_NAME,
+      Key: { pk: { S: `SITE#${siteId}` }, sk: { S: `QUOTA#${monthKey()}` } },
+      UpdateExpression: 'ADD #c :one SET #t = if_not_exists(#t, :ttl)',
+      ExpressionAttributeNames: { '#c': 'count', '#t': 'ttl' },
+      ExpressionAttributeValues: { ':one': { N: '1' }, ':ttl': { N: String(Math.floor(Date.now() / 1000) + 70 * 24 * 3600) } },
+      ReturnValues: 'UPDATED_NEW',
+    }) as { Attributes?: Record<string, unknown> }
+    const count = res.Attributes ? (unmarshall(res.Attributes).count as number) : 0
+    return !quotaExceeded(count, MONTHLY_EVENT_QUOTA)
+  }
+catch (e) {
+    console.error('Quota check failed:', (e as Error).message)
+    return true
+  }
+}

package/src/lib/rate-limit.ts

@@ -0,0 +1,27 @@
+/**
+ * In-memory fixed-window rate limiter.
+ *
+ * Keyed by an arbitrary string (e.g. an API key id). Good enough for a single
+ * server process; a multi-instance deploy would back this with DynamoDB/Redis,
+ * but this closes the "no enforcement at all" gap and returns 429 on abuse.
+ */
+interface Bucket { count: number; resetAt: number }
+
+const buckets = new Map<string, Bucket>()
+
+/** Returns true if the request is allowed, false if the key is over its limit. */
+export function rateLimitAllow(key: string, limit: number, windowMs: number): boolean {
+  const now = Date.now()
+  let b = buckets.get(key)
+  if (!b || b.resetAt <= now) {
+    b = { count: 0, resetAt: now + windowMs }
+    buckets.set(key, b)
+  }
+  b.count++
+  return b.count <= limit
+}
+
+/** Test/util: clear all buckets. */
+export function resetRateLimits(): void {
+  buckets.clear()
+}