@sixb/core 0.1.20 → 0.1.21

package/src/activity/execution.ts

@@ -0,0 +1,210 @@
+import { AuthorizationError, assertAuthorized } from "../authorization"
+import { getAuthorizationRef } from "../execution/authorization"
+import type { SixbRuntimeContext } from "../runtime/types"
+import type { ActivityEventInput, ActivitySummary, ActivityUser } from "../storage/activity/types"
+import {
+  type ActivityConnectionsPage,
+  type ActivityConnectionsQuery,
+  readActivityConnections,
+} from "./connection"
+import type {
+  ActivityCalendar,
+  ActivityCalendarQuery,
+  ActivityCaptureOptions,
+  ActivityCaptureResult,
+  ActivityPageQuery,
+  ActivityPeriodQuery,
+  ActivityService,
+  ActivitySource,
+} from "./service"
+import { type ActivityVisitView, nameSharedVisit, nameSharedVisits } from "./shares"
+import {
+  ACTIVITY_TIMELINE_LIMIT,
+  type ActivityVisitTimeline,
+  composeActivityTimeline,
+} from "./timeline"
+
+export interface ActivityVisitList {
+  readonly visits: readonly ActivityVisitView[]
+  readonly hasMore: boolean
+}
+
+export interface ActivityUsersResult {
+  /** `displayName` is the account's profile name; no other profile field is read. */
+  readonly users: readonly (ActivityUser & { readonly displayName?: string })[]
+  readonly hasMore: boolean
+}
+
+/** `sixb.activity`: the app's recorded visits. Every read needs `can.observe(project.activity)`. */
+export interface ActivityRuntime {
+  /** Shared visits name their link's share: see `ActivityVisitView`. */
+  list(query: ActivityPageQuery): Promise<ActivityVisitList>
+  users(query: ActivityPageQuery): Promise<ActivityUsersResult>
+  summarize(query: ActivityPeriodQuery): Promise<ActivitySummary>
+  calendar(query: ActivityCalendarQuery): Promise<ActivityCalendar>
+  /**
+   * The visit's page views and interactions with the actions, workflows and Agent runs its session
+   * started, and the connection it came through. Bounded: see `truncated`.
+   */
+  timeline(visitId: string): Promise<ActivityVisitTimeline | null>
+  /** A user's sign-ins, newest first, with the visits each opened. */
+  connections(query: ActivityConnectionsQuery): Promise<ActivityConnectionsPage>
+}
+
+/**
+ * Recording, for the server's capture route only: it is not on `sixb.activity`, so project code
+ * cannot record visits under whatever authority it runs with.
+ */
+export interface ActivityCaptureRuntime {
+  /** The settings a browser session reads before it sends anything. */
+  captureOptions(): ActivityCaptureOptions
+  /** Records a batch for the calling user or shared session. */
+  capture(events: readonly ActivityEventInput[]): Promise<ActivityCaptureResult>
+}
+
+// Display names are read one account at a time; a page of users reads a few at once.
+const PROFILE_READ_CONCURRENCY = 8
+
+export function createActivityRuntime(
+  runtime: SixbRuntimeContext,
+  service: ActivityService
+): ActivityRuntime {
+  const assertObservable = () => assertAuthorized(runtime, { kind: "activity.observe" })
+
+  return {
+    async list(query) {
+      assertObservable()
+      const page = await service.list(query)
+      return { ...page, visits: await nameSharedVisits(runtime, page.visits) }
+    },
+
+    async users(query) {
+      assertObservable()
+      const page = await service.users(query)
+
+      // Only accounts in this bounded page are looked up, and only their name is kept.
+      const users = await mapInChunks(page.users, PROFILE_READ_CONCURRENCY, async (user) => {
+        const profile = await runtime.storage.auth?.users.getById({
+          projectId: runtime.projectId,
+          id: user.userId,
+        })
+        return profile?.displayName ? { ...user, displayName: profile.displayName } : user
+      })
+
+      return { users, hasMore: page.hasMore }
+    },
+
+    async summarize(query) {
+      assertObservable()
+      return service.summarize(query)
+    },
+
+    async calendar(query) {
+      assertObservable()
+      return service.calendar(query)
+    },
+
+    async timeline(visitId) {
+      assertObservable()
+      const page = await service.readWithSession({ id: visitId, limit: ACTIVITY_TIMELINE_LIMIT })
+      if (!page) {
+        return null
+      }
+
+      const shared = await nameSharedVisit(runtime, page.visit)
+      return composeActivityTimeline(runtime, { ...shared, page }, new Date())
+    },
+
+    async connections(query) {
+      assertObservable()
+      return readActivityConnections(runtime, service, query, new Date())
+    },
+  }
+}
+
+export function createActivityCaptureRuntime(
+  runtime: SixbRuntimeContext,
+  service: ActivityService
+): ActivityCaptureRuntime {
+  return {
+    captureOptions() {
+      captureSource(runtime)
+      return service.captureOptions
+    },
+
+    async capture(events) {
+      return service.capture(captureSource(runtime), events)
+    },
+  }
+}
+
+const activityCaptureKey: unique symbol = Symbol("sixb.activityCapture")
+
+interface ActivityCaptureOwner {
+  readonly [activityCaptureKey]?: ActivityCaptureRuntime
+}
+
+export function registerActivityCaptureRuntime(
+  owner: object,
+  capture: ActivityCaptureRuntime
+): void {
+  Object.defineProperty(owner, activityCaptureKey, {
+    configurable: false,
+    enumerable: false,
+    value: capture,
+    writable: false,
+  })
+}
+
+/** The recording side of a bound SDK, such as a request's. */
+export function getActivityCaptureRuntime(owner: object): ActivityCaptureRuntime {
+  const capture = (owner as ActivityCaptureOwner)[activityCaptureKey]
+  if (!capture) {
+    throw new Error("[Sixb] Activity capture is not registered for this execution.")
+  }
+  return capture
+}
+
+/**
+ * The session the batch came through, from verified authorization only. A browser never names an
+ * actor, and an access token or a trusted primitive is not a visit.
+ */
+function captureSource(runtime: SixbRuntimeContext): ActivitySource {
+  const ref = getAuthorizationRef(runtime.runtimeAuthorization)
+
+  if (
+    ref.type === "principal" &&
+    ref.principal.type === "user" &&
+    ref.credential?.type === "session"
+  ) {
+    return {
+      actor: { type: "user", userId: ref.principal.id },
+      sessionId: ref.credential.id,
+    }
+  }
+
+  if (ref.type === "delegated") {
+    return {
+      actor: { type: "share", grantId: ref.delegation.grantId },
+      sessionId: ref.delegation.sessionId,
+    }
+  }
+
+  throw new AuthorizationError(
+    "activity.capture",
+    "[Sixb] Activity is recorded only for a signed-in user's session or a shared link's session."
+  )
+}
+
+async function mapInChunks<T, R>(
+  items: readonly T[],
+  size: number,
+  map: (item: T) => Promise<R>
+): Promise<R[]> {
+  const results: R[] = []
+  for (let start = 0; start < items.length; start += size) {
+    const chunk = await Promise.all(items.slice(start, start + size).map(map))
+    results.push(...chunk)
+  }
+  return results
+}

package/src/activity/service.ts

@@ -0,0 +1,274 @@
+import { randomUUID } from "node:crypto"
+import {
+  ACTIVITY_ID_MAX_LENGTH,
+  ACTIVITY_MAX_PAGE_SIZE,
+  ACTIVITY_MAX_PERIOD_MS,
+  ACTIVITY_MIN_IDLE_TIMEOUT_MS,
+  ACTIVITY_VISIT_ID_PATTERN,
+  validateActivityEvents,
+} from "../storage/activity/policy"
+import type {
+  ActivityActor,
+  ActivityCursor,
+  ActivityDay,
+  ActivityEventInput,
+  ActivityPeriodInput,
+  ActivitySessionVisits,
+  ActivityStorage,
+  ActivitySummary,
+  ActivityUsersPage,
+  ActivityVisitsPage,
+  ListActivitySessionVisitsInput,
+  StoredActivityVisitPage,
+} from "../storage/activity/types"
+import {
+  type ActivityConnectionsCursor,
+  type ActivityConnectionsQuery,
+  decodeActivityConnectionsCursor,
+} from "./connection"
+
+export interface ActivityOptions {
+  /**
+   * Record visits, page views and marked interactions in the project's app and its shared links.
+   * Off by default.
+   */
+  readonly enabled?: boolean
+  /** A new visit begins after this long without foreground activity. Default: 30 minutes. */
+  readonly idleTimeoutMs?: number
+}
+
+/** What a browser needs to know before it sends anything. */
+export interface ActivityCaptureOptions {
+  readonly enabled: boolean
+  readonly idleTimeoutMs: number
+}
+
+export interface ActivityCaptureResult {
+  readonly status: "accepted" | "throttled" | "disabled"
+  readonly accepted: number
+}
+
+/** Visits active in `[from, to)`, at most 31 days, and the page views received in it. */
+export interface ActivityPeriodQuery {
+  readonly from: Date
+  readonly to: Date
+  /** Only this account's visits. */
+  readonly userId?: string
+}
+
+export interface ActivityPageQuery extends ActivityPeriodQuery {
+  /** 1 to 100. Default: 50. */
+  readonly limit?: number
+  /** The last row of the previous page: its `lastSeenAt`, and its visit or user id. */
+  readonly before?: ActivityCursor
+}
+
+export interface ActivityCalendarQuery {
+  readonly userId: string
+  /** A UTC calendar year. */
+  readonly year: number
+}
+
+export interface ActivityCalendar {
+  readonly userId: string
+  readonly year: number
+  readonly days: readonly ActivityDay[]
+}
+
+/** The session whose browser sent a batch, from its verified authorization. */
+export interface ActivitySource {
+  readonly actor: ActivityActor
+  readonly sessionId: string
+}
+
+const DEFAULT_IDLE_TIMEOUT_MS = 30 * 60_000
+const ACTIVITY_CONNECTION_VISITS = 5
+const MAX_IDLE_TIMEOUT_MS = 24 * 60 * 60_000
+
+/** Validates queries and holds the project's activity settings. Authorization is the caller's. */
+export class ActivityService {
+  readonly captureOptions: ActivityCaptureOptions
+
+  constructor(
+    private readonly projectId: string,
+    private readonly storage: ActivityStorage | undefined,
+    options: ActivityOptions = {},
+    private readonly now = () => new Date()
+  ) {
+    const idleTimeoutMs = options.idleTimeoutMs ?? DEFAULT_IDLE_TIMEOUT_MS
+    if (
+      !Number.isSafeInteger(idleTimeoutMs) ||
+      idleTimeoutMs < ACTIVITY_MIN_IDLE_TIMEOUT_MS ||
+      idleTimeoutMs > MAX_IDLE_TIMEOUT_MS
+    ) {
+      throw new Error(
+        `[Sixb] activity.idleTimeoutMs must be an integer between ${ACTIVITY_MIN_IDLE_TIMEOUT_MS} and ${MAX_IDLE_TIMEOUT_MS} milliseconds.`
+      )
+    }
+
+    this.captureOptions = Object.freeze({ enabled: options.enabled === true, idleTimeoutMs })
+
+    if (this.captureOptions.enabled && !storage) {
+      throw new Error(
+        "[Sixb] activity.enabled needs a storage with an activity store, such as a migrated SQLite or PostgreSQL storage."
+      )
+    }
+  }
+
+  async capture(
+    source: ActivitySource,
+    events: readonly ActivityEventInput[]
+  ): Promise<ActivityCaptureResult> {
+    validateActivityEvents(events)
+
+    if (!this.captureOptions.enabled) {
+      return { status: "disabled", accepted: 0 }
+    }
+
+    return this.requireStorage().append({
+      projectId: this.projectId,
+      actor: source.actor,
+      sessionId: source.sessionId,
+      events,
+      now: this.now(),
+      idleTimeoutMs: this.captureOptions.idleTimeoutMs,
+      newVisitId: `visit_${randomUUID()}`,
+    })
+  }
+
+  list(query: ActivityPageQuery): Promise<ActivityVisitsPage> {
+    return this.requireStorage().list({
+      ...this.period(query),
+      limit: pageLimit(query.limit),
+      before: cursor(query.before),
+    })
+  }
+
+  users(query: ActivityPageQuery): Promise<ActivityUsersPage> {
+    return this.requireStorage().users({
+      ...this.period(query),
+      limit: pageLimit(query.limit),
+      before: cursor(query.before),
+    })
+  }
+
+  summarize(query: ActivityPeriodQuery): Promise<ActivitySummary> {
+    return this.requireStorage().summarize(this.period(query))
+  }
+
+  async calendar(query: ActivityCalendarQuery): Promise<ActivityCalendar> {
+    validateUserId(query.userId)
+
+    if (!Number.isSafeInteger(query.year) || query.year < 1970 || query.year > 9998) {
+      throw new Error("[Sixb] Activity calendar year must be between 1970 and 9998.")
+    }
+
+    const days = await this.requireStorage().calendar({
+      projectId: this.projectId,
+      userId: query.userId,
+      from: new Date(Date.UTC(query.year, 0, 1)),
+      to: new Date(Date.UTC(query.year + 1, 0, 1)),
+    })
+
+    return { userId: query.userId, year: query.year, days }
+  }
+
+  /**
+   * A visit, its first page views, and the session it belongs to: the timeline joins on it, and it
+   * never leaves core.
+   */
+  readWithSession(input: {
+    readonly id: string
+    readonly limit: number
+  }): Promise<StoredActivityVisitPage | null> {
+    if (typeof input.id !== "string" || !ACTIVITY_VISIT_ID_PATTERN.test(input.id)) {
+      throw new Error("[Sixb] Invalid activity visit id.")
+    }
+
+    return this.requireStorage().read({
+      projectId: this.projectId,
+      id: input.id,
+      limit: input.limit,
+    })
+  }
+
+  connectionsQuery(query: ActivityConnectionsQuery): {
+    readonly userId: string
+    readonly limit: number
+    readonly before?: ActivityConnectionsCursor
+  } {
+    validateUserId(query.userId)
+
+    return {
+      userId: query.userId,
+      limit: pageLimit(query.limit ?? 20),
+      ...(query.cursor === undefined
+        ? {}
+        : { before: decodeActivityConnectionsCursor(query.cursor) }),
+    }
+  }
+
+  /** Each session's visit count and latest visits: a connection shows those, the calendar the rest. */
+  sessionVisits(
+    input: Omit<ListActivitySessionVisitsInput, "projectId" | "limit">
+  ): Promise<readonly ActivitySessionVisits[]> {
+    return this.requireStorage().sessionVisits({
+      ...input,
+      projectId: this.projectId,
+      limit: ACTIVITY_CONNECTION_VISITS,
+    })
+  }
+
+  private period(query: ActivityPeriodQuery): ActivityPeriodInput {
+    if (query.userId !== undefined) {
+      validateUserId(query.userId)
+    }
+
+    const from = query.from.getTime()
+    const to = query.to.getTime()
+    if (
+      !Number.isFinite(from) ||
+      !Number.isFinite(to) ||
+      from >= to ||
+      to - from > ACTIVITY_MAX_PERIOD_MS
+    ) {
+      throw new Error("[Sixb] Activity queries require an ordered period of at most 31 days.")
+    }
+
+    return { projectId: this.projectId, from: query.from, to: query.to, userId: query.userId }
+  }
+
+  private requireStorage(): ActivityStorage {
+    if (!this.storage) {
+      throw new Error("[Sixb] This project's storage has no activity store.")
+    }
+    return this.storage
+  }
+}
+
+function validateUserId(value: string): void {
+  if (typeof value !== "string" || !value.trim() || value.length > ACTIVITY_ID_MAX_LENGTH) {
+    throw new Error(
+      `[Sixb] Activity userId must be a nonempty user id of at most ${ACTIVITY_ID_MAX_LENGTH} characters.`
+    )
+  }
+}
+
+function cursor(value: ActivityCursor | undefined): ActivityCursor | undefined {
+  if (
+    value &&
+    (!Number.isFinite(value.at.getTime()) ||
+      !value.id.trim() ||
+      value.id.length > ACTIVITY_ID_MAX_LENGTH)
+  ) {
+    throw new Error("[Sixb] Invalid activity cursor.")
+  }
+  return value
+}
+
+function pageLimit(value = 50): number {
+  if (!Number.isSafeInteger(value) || value < 1 || value > ACTIVITY_MAX_PAGE_SIZE) {
+    throw new Error(`[Sixb] Activity page size must be between 1 and ${ACTIVITY_MAX_PAGE_SIZE}.`)
+  }
+  return value
+}

package/src/activity/shares.ts

@@ -0,0 +1,62 @@
+import type { SixbRuntimeContext } from "../runtime/types"
+import type { ActivityActor, ActivityVisit } from "../storage/activity/types"
+import type { ShareGrantRecord } from "../storage/share-grants"
+
+/** Who a visit belongs to, as `sixb.activity` returns it: a shared link also names its share. */
+export type ActivityVisitActor =
+  | Extract<ActivityActor, { readonly type: "user" }>
+  | (Extract<ActivityActor, { readonly type: "share" }> & {
+      /** The link's share definition; absent once its grant is gone. */
+      readonly definitionId?: string
+    })
+
+/** A visit as `sixb.activity` returns it. */
+export interface ActivityVisitView extends Omit<ActivityVisit, "actor"> {
+  readonly actor: ActivityVisitActor
+}
+
+/** Visits named by their links' shares, from one grant read for all of them. */
+export async function nameSharedVisits(
+  runtime: SixbRuntimeContext,
+  visits: readonly ActivityVisit[]
+): Promise<readonly ActivityVisitView[]> {
+  const grants = await readGrants(runtime, visits)
+  return visits.map((visit) => withShare(visit, grants))
+}
+
+/** One visit named by its link's share, with that link's grant when it still exists. */
+export async function nameSharedVisit(
+  runtime: SixbRuntimeContext,
+  visit: ActivityVisit
+): Promise<{ readonly visit: ActivityVisitView; readonly grant?: ShareGrantRecord }> {
+  const grants = await readGrants(runtime, [visit])
+  const grant = visit.actor.type === "share" ? grants.get(visit.actor.grantId) : undefined
+
+  return { visit: withShare(visit, grants), ...(grant === undefined ? {} : { grant }) }
+}
+
+async function readGrants(
+  runtime: SixbRuntimeContext,
+  visits: readonly ActivityVisit[]
+): Promise<ReadonlyMap<string, ShareGrantRecord>> {
+  const ids = visits.flatMap((visit) => (visit.actor.type === "share" ? [visit.actor.grantId] : []))
+  if (ids.length === 0 || !runtime.storage.shareGrants) {
+    return new Map()
+  }
+
+  const grants = await runtime.storage.shareGrants.getByIds({ projectId: runtime.projectId, ids })
+  return new Map(grants.map((grant) => [grant.id, grant]))
+}
+
+function withShare(
+  visit: ActivityVisit,
+  grants: ReadonlyMap<string, ShareGrantRecord>
+): ActivityVisitView {
+  const { actor } = visit
+  const grant = actor.type === "share" ? grants.get(actor.grantId) : undefined
+  if (actor.type !== "share" || grant === undefined) {
+    return visit
+  }
+
+  return { ...visit, actor: { ...actor, definitionId: grant.definitionId } }
+}