@vellumai/assistant 0.3.5 → 0.3.7

package/src/memory/ingress-invite-store.ts

@@ -0,0 +1,338 @@
+/**
+ * CRUD store for assistant ingress invites.
+ *
+ * Invites allow external users to join an assistant's ingress (inbox) on a
+ * specific channel. Each invite carries a SHA-256 hashed token — the raw
+ * token is returned exactly once at creation time and never stored.
+ */
+
+import { and, desc, eq } from 'drizzle-orm';
+import { createHash, randomBytes, randomUUID } from 'node:crypto';
+import { getDb } from './db.js';
+import { assistantIngressInvites, assistantIngressMembers } from './schema.js';
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export type InviteStatus = 'active' | 'redeemed' | 'revoked' | 'expired';
+
+export interface IngressInvite {
+  id: string;
+  assistantId: string;
+  sourceChannel: string;
+  tokenHash: string;
+  createdBySessionId: string | null;
+  note: string | null;
+  maxUses: number;
+  useCount: number;
+  expiresAt: number;
+  status: InviteStatus;
+  redeemedByExternalUserId: string | null;
+  redeemedByExternalChatId: string | null;
+  redeemedAt: number | null;
+  createdAt: number;
+  updatedAt: number;
+}
+
+export interface IngressMember {
+  id: string;
+  assistantId: string;
+  sourceChannel: string;
+  externalUserId: string | null;
+  externalChatId: string | null;
+  displayName: string | null;
+  username: string | null;
+  status: string;
+  policy: string;
+  inviteId: string | null;
+  createdBySessionId: string | null;
+  revokedReason: string | null;
+  blockedReason: string | null;
+  lastSeenAt: number | null;
+  createdAt: number;
+  updatedAt: number;
+}
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+const DEFAULT_EXPIRY_MS = 7 * 24 * 60 * 60 * 1000; // 7 days
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function hashToken(rawToken: string): string {
+  return createHash('sha256').update(rawToken).digest('hex');
+}
+
+function generateToken(): string {
+  // 32 bytes = 256 bits of entropy, base64url-encoded to a 43-character URL-safe string.
+  return randomBytes(32).toString('base64url');
+}
+
+function rowToInvite(row: typeof assistantIngressInvites.$inferSelect): IngressInvite {
+  return {
+    id: row.id,
+    assistantId: row.assistantId,
+    sourceChannel: row.sourceChannel,
+    tokenHash: row.tokenHash,
+    createdBySessionId: row.createdBySessionId,
+    note: row.note,
+    maxUses: row.maxUses,
+    useCount: row.useCount,
+    expiresAt: row.expiresAt,
+    status: row.status as InviteStatus,
+    redeemedByExternalUserId: row.redeemedByExternalUserId,
+    redeemedByExternalChatId: row.redeemedByExternalChatId,
+    redeemedAt: row.redeemedAt,
+    createdAt: row.createdAt,
+    updatedAt: row.updatedAt,
+  };
+}
+
+function rowToMember(row: typeof assistantIngressMembers.$inferSelect): IngressMember {
+  return {
+    id: row.id,
+    assistantId: row.assistantId,
+    sourceChannel: row.sourceChannel,
+    externalUserId: row.externalUserId,
+    externalChatId: row.externalChatId,
+    displayName: row.displayName,
+    username: row.username,
+    status: row.status,
+    policy: row.policy,
+    inviteId: row.inviteId,
+    createdBySessionId: row.createdBySessionId,
+    revokedReason: row.revokedReason,
+    blockedReason: row.blockedReason,
+    lastSeenAt: row.lastSeenAt,
+    createdAt: row.createdAt,
+    updatedAt: row.updatedAt,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// createInvite
+// ---------------------------------------------------------------------------
+
+export function createInvite(params: {
+  assistantId?: string;
+  sourceChannel: string;
+  createdBySessionId?: string;
+  note?: string;
+  maxUses?: number;
+  expiresInMs?: number;
+}): { invite: IngressInvite; rawToken: string } {
+  const db = getDb();
+  const now = Date.now();
+  const id = randomUUID();
+  const rawToken = generateToken();
+  const tokenH = hashToken(rawToken);
+
+  const row = {
+    id,
+    assistantId: params.assistantId ?? 'self',
+    sourceChannel: params.sourceChannel,
+    tokenHash: tokenH,
+    createdBySessionId: params.createdBySessionId ?? null,
+    note: params.note ?? null,
+    maxUses: params.maxUses ?? 1,
+    useCount: 0,
+    expiresAt: now + (params.expiresInMs ?? DEFAULT_EXPIRY_MS),
+    status: 'active' as const,
+    redeemedByExternalUserId: null,
+    redeemedByExternalChatId: null,
+    redeemedAt: null,
+    createdAt: now,
+    updatedAt: now,
+  };
+
+  db.insert(assistantIngressInvites).values(row).run();
+
+  return { invite: rowToInvite(row), rawToken };
+}
+
+// ---------------------------------------------------------------------------
+// listInvites
+// ---------------------------------------------------------------------------
+
+export function listInvites(params: {
+  assistantId?: string;
+  sourceChannel?: string;
+  status?: InviteStatus;
+  limit?: number;
+  offset?: number;
+}): IngressInvite[] {
+  const db = getDb();
+  const assistantId = params.assistantId ?? 'self';
+
+  const conditions = [eq(assistantIngressInvites.assistantId, assistantId)];
+
+  if (params.sourceChannel) {
+    conditions.push(eq(assistantIngressInvites.sourceChannel, params.sourceChannel));
+  }
+  if (params.status) {
+    conditions.push(eq(assistantIngressInvites.status, params.status));
+  }
+
+  const rows = db
+    .select()
+    .from(assistantIngressInvites)
+    .where(and(...conditions))
+    .orderBy(desc(assistantIngressInvites.createdAt))
+    .limit(params.limit ?? 100)
+    .offset(params.offset ?? 0)
+    .all();
+
+  return rows.map(rowToInvite);
+}
+
+// ---------------------------------------------------------------------------
+// revokeInvite
+// ---------------------------------------------------------------------------
+
+export function revokeInvite(inviteId: string): IngressInvite | null {
+  const db = getDb();
+  const now = Date.now();
+
+  const existing = db
+    .select()
+    .from(assistantIngressInvites)
+    .where(
+      and(
+        eq(assistantIngressInvites.id, inviteId),
+        eq(assistantIngressInvites.status, 'active'),
+      ),
+    )
+    .get();
+
+  if (!existing) return null;
+
+  db.update(assistantIngressInvites)
+    .set({ status: 'revoked', updatedAt: now })
+    .where(eq(assistantIngressInvites.id, inviteId))
+    .run();
+
+  return rowToInvite({ ...existing, status: 'revoked', updatedAt: now });
+}
+
+// ---------------------------------------------------------------------------
+// redeemInvite
+// ---------------------------------------------------------------------------
+
+export interface RedeemError {
+  error: string;
+}
+
+export function redeemInvite(params: {
+  rawToken: string;
+  externalUserId?: string;
+  externalChatId?: string;
+  displayName?: string;
+  username?: string;
+  sourceChannel?: string;
+}): { invite: IngressInvite; member: IngressMember } | RedeemError {
+  const db = getDb();
+  const now = Date.now();
+  const tokenH = hashToken(params.rawToken);
+
+  const invite = db
+    .select()
+    .from(assistantIngressInvites)
+    .where(eq(assistantIngressInvites.tokenHash, tokenH))
+    .get();
+
+  if (!invite) {
+    return { error: 'invite_not_found' };
+  }
+
+  if (invite.status !== 'active') {
+    return { error: `invite_${invite.status}` };
+  }
+
+  if (invite.expiresAt <= now) {
+    // Mark as expired for future lookups
+    db.update(assistantIngressInvites)
+      .set({ status: 'expired', updatedAt: now })
+      .where(eq(assistantIngressInvites.id, invite.id))
+      .run();
+    return { error: 'invite_expired' };
+  }
+
+  if (invite.useCount >= invite.maxUses) {
+    return { error: 'invite_max_uses_reached' };
+  }
+
+  const newUseCount = invite.useCount + 1;
+  const newStatus = newUseCount >= invite.maxUses ? 'redeemed' : 'active';
+
+  // Update invite in a transaction with member creation
+  const memberId = randomUUID();
+  const sourceChannel = params.sourceChannel ?? invite.sourceChannel;
+
+  const memberRow = {
+    id: memberId,
+    assistantId: invite.assistantId,
+    sourceChannel,
+    externalUserId: params.externalUserId ?? null,
+    externalChatId: params.externalChatId ?? null,
+    displayName: params.displayName ?? null,
+    username: params.username ?? null,
+    status: 'active' as const,
+    policy: 'allow' as const,
+    inviteId: invite.id,
+    createdBySessionId: null,
+    revokedReason: null,
+    blockedReason: null,
+    lastSeenAt: null,
+    createdAt: now,
+    updatedAt: now,
+  };
+
+  db.transaction((tx) => {
+    tx.update(assistantIngressInvites)
+      .set({
+        useCount: newUseCount,
+        status: newStatus,
+        redeemedByExternalUserId: params.externalUserId ?? null,
+        redeemedByExternalChatId: params.externalChatId ?? null,
+        redeemedAt: now,
+        updatedAt: now,
+      })
+      .where(eq(assistantIngressInvites.id, invite.id))
+      .run();
+
+    tx.insert(assistantIngressMembers).values(memberRow).run();
+  });
+
+  const updatedInvite: IngressInvite = {
+    ...rowToInvite(invite),
+    useCount: newUseCount,
+    status: newStatus as InviteStatus,
+    redeemedByExternalUserId: params.externalUserId ?? null,
+    redeemedByExternalChatId: params.externalChatId ?? null,
+    redeemedAt: now,
+    updatedAt: now,
+  };
+
+  return { invite: updatedInvite, member: rowToMember(memberRow) };
+}
+
+// ---------------------------------------------------------------------------
+// findByTokenHash
+// ---------------------------------------------------------------------------
+
+export function findByTokenHash(tokenHash: string): IngressInvite | null {
+  const db = getDb();
+
+  const row = db
+    .select()
+    .from(assistantIngressInvites)
+    .where(eq(assistantIngressInvites.tokenHash, tokenHash))
+    .get();
+
+  return row ? rowToInvite(row) : null;
+}

package/src/memory/ingress-member-store.ts

@@ -0,0 +1,350 @@
+/**
+ * CRUD store for assistant ingress members — external users who have been
+ * granted (or denied) access to interact with the assistant via a specific
+ * channel. Members are keyed by raw channel identity fields (sourceChannel +
+ * externalUserId / externalChatId).
+ */
+
+import { and, desc, eq, or } from 'drizzle-orm';
+import { v4 as uuid } from 'uuid';
+import { getDb } from './db.js';
+import { assistantIngressMembers } from './schema.js';
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export type MemberStatus = 'pending' | 'active' | 'revoked' | 'blocked';
+export type MemberPolicy = 'allow' | 'deny' | 'escalate';
+
+export interface IngressMember {
+  id: string;
+  assistantId: string;
+  sourceChannel: string;
+  externalUserId: string | null;
+  externalChatId: string | null;
+  displayName: string | null;
+  username: string | null;
+  status: MemberStatus;
+  policy: MemberPolicy;
+  inviteId: string | null;
+  createdBySessionId: string | null;
+  revokedReason: string | null;
+  blockedReason: string | null;
+  lastSeenAt: number | null;
+  createdAt: number;
+  updatedAt: number;
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function rowToMember(row: typeof assistantIngressMembers.$inferSelect): IngressMember {
+  return {
+    id: row.id,
+    assistantId: row.assistantId,
+    sourceChannel: row.sourceChannel,
+    externalUserId: row.externalUserId,
+    externalChatId: row.externalChatId,
+    displayName: row.displayName,
+    username: row.username,
+    status: row.status as MemberStatus,
+    policy: row.policy as MemberPolicy,
+    inviteId: row.inviteId,
+    createdBySessionId: row.createdBySessionId,
+    revokedReason: row.revokedReason,
+    blockedReason: row.blockedReason,
+    lastSeenAt: row.lastSeenAt,
+    createdAt: row.createdAt,
+    updatedAt: row.updatedAt,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// upsertMember
+// ---------------------------------------------------------------------------
+
+export function upsertMember(params: {
+  sourceChannel: string;
+  externalUserId?: string;
+  externalChatId?: string;
+  displayName?: string;
+  username?: string;
+  policy?: MemberPolicy;
+  status?: MemberStatus;
+  inviteId?: string;
+  createdBySessionId?: string;
+  assistantId?: string;
+}): IngressMember {
+  const assistantId = params.assistantId ?? 'self';
+
+  if (!params.externalUserId && !params.externalChatId) {
+    throw new Error('At least one of externalUserId or externalChatId must be provided');
+  }
+
+  const db = getDb();
+  const now = Date.now();
+
+  // Try to find an existing member by (assistantId, sourceChannel, externalUserId)
+  // or (assistantId, sourceChannel, externalChatId)
+  const matchConditions = [];
+  if (params.externalUserId) {
+    matchConditions.push(
+      and(
+        eq(assistantIngressMembers.assistantId, assistantId),
+        eq(assistantIngressMembers.sourceChannel, params.sourceChannel),
+        eq(assistantIngressMembers.externalUserId, params.externalUserId),
+      ),
+    );
+  }
+  if (params.externalChatId) {
+    matchConditions.push(
+      and(
+        eq(assistantIngressMembers.assistantId, assistantId),
+        eq(assistantIngressMembers.sourceChannel, params.sourceChannel),
+        eq(assistantIngressMembers.externalChatId, params.externalChatId),
+      ),
+    );
+  }
+
+  const existing = db
+    .select()
+    .from(assistantIngressMembers)
+    .where(matchConditions.length === 1 ? matchConditions[0] : or(...matchConditions))
+    .get();
+
+  if (existing) {
+    // Update the existing member
+    const updates: Record<string, unknown> = { updatedAt: now };
+    if (params.externalUserId !== undefined) updates.externalUserId = params.externalUserId;
+    if (params.externalChatId !== undefined) updates.externalChatId = params.externalChatId;
+    if (params.displayName !== undefined) updates.displayName = params.displayName;
+    if (params.username !== undefined) updates.username = params.username;
+    if (params.policy !== undefined) updates.policy = params.policy;
+    if (params.status !== undefined) updates.status = params.status;
+    if (params.inviteId !== undefined) updates.inviteId = params.inviteId;
+    if (params.createdBySessionId !== undefined) updates.createdBySessionId = params.createdBySessionId;
+
+    db.update(assistantIngressMembers)
+      .set(updates)
+      .where(eq(assistantIngressMembers.id, existing.id))
+      .run();
+
+    // Re-read to return the updated row
+    const updated = db
+      .select()
+      .from(assistantIngressMembers)
+      .where(eq(assistantIngressMembers.id, existing.id))
+      .get();
+
+    return rowToMember(updated!);
+  }
+
+  // Create a new member
+  const id = uuid();
+  const row = {
+    id,
+    assistantId,
+    sourceChannel: params.sourceChannel,
+    externalUserId: params.externalUserId ?? null,
+    externalChatId: params.externalChatId ?? null,
+    displayName: params.displayName ?? null,
+    username: params.username ?? null,
+    status: params.status ?? 'pending',
+    policy: params.policy ?? 'allow',
+    inviteId: params.inviteId ?? null,
+    createdBySessionId: params.createdBySessionId ?? null,
+    revokedReason: null,
+    blockedReason: null,
+    lastSeenAt: null,
+    createdAt: now,
+    updatedAt: now,
+  };
+
+  db.insert(assistantIngressMembers).values(row).run();
+
+  return rowToMember(row);
+}
+
+// ---------------------------------------------------------------------------
+// listMembers
+// ---------------------------------------------------------------------------
+
+export function listMembers(params?: {
+  assistantId?: string;
+  sourceChannel?: string;
+  status?: MemberStatus;
+  policy?: MemberPolicy;
+  limit?: number;
+  offset?: number;
+}): IngressMember[] {
+  const db = getDb();
+  const assistantId = params?.assistantId ?? 'self';
+
+  const conditions = [eq(assistantIngressMembers.assistantId, assistantId)];
+  if (params?.sourceChannel) {
+    conditions.push(eq(assistantIngressMembers.sourceChannel, params.sourceChannel));
+  }
+  if (params?.status) {
+    conditions.push(eq(assistantIngressMembers.status, params.status));
+  }
+  if (params?.policy) {
+    conditions.push(eq(assistantIngressMembers.policy, params.policy));
+  }
+
+  let query = db
+    .select()
+    .from(assistantIngressMembers)
+    .where(and(...conditions))
+    .orderBy(desc(assistantIngressMembers.updatedAt))
+    .$dynamic();
+
+  if (params?.limit !== undefined) {
+    query = query.limit(params.limit);
+  }
+  if (params?.offset !== undefined) {
+    query = query.offset(params.offset);
+  }
+
+  return query.all().map(rowToMember);
+}
+
+// ---------------------------------------------------------------------------
+// revokeMember
+// ---------------------------------------------------------------------------
+
+export function revokeMember(memberId: string, reason?: string): IngressMember | null {
+  const db = getDb();
+  const now = Date.now();
+
+  const existing = db
+    .select()
+    .from(assistantIngressMembers)
+    .where(eq(assistantIngressMembers.id, memberId))
+    .get();
+
+  if (!existing) return null;
+
+  // Only revoke from active or pending status
+  if (existing.status !== 'active' && existing.status !== 'pending') {
+    return null;
+  }
+
+  db.update(assistantIngressMembers)
+    .set({
+      status: 'revoked',
+      revokedReason: reason ?? null,
+      updatedAt: now,
+    })
+    .where(eq(assistantIngressMembers.id, memberId))
+    .run();
+
+  const updated = db
+    .select()
+    .from(assistantIngressMembers)
+    .where(eq(assistantIngressMembers.id, memberId))
+    .get();
+
+  return updated ? rowToMember(updated) : null;
+}
+
+// ---------------------------------------------------------------------------
+// blockMember
+// ---------------------------------------------------------------------------
+
+export function blockMember(memberId: string, reason?: string): IngressMember | null {
+  const db = getDb();
+  const now = Date.now();
+
+  const existing = db
+    .select()
+    .from(assistantIngressMembers)
+    .where(eq(assistantIngressMembers.id, memberId))
+    .get();
+
+  if (!existing) return null;
+
+  // Can block from any non-blocked status
+  if (existing.status === 'blocked') {
+    return null;
+  }
+
+  db.update(assistantIngressMembers)
+    .set({
+      status: 'blocked',
+      blockedReason: reason ?? null,
+      updatedAt: now,
+    })
+    .where(eq(assistantIngressMembers.id, memberId))
+    .run();
+
+  const updated = db
+    .select()
+    .from(assistantIngressMembers)
+    .where(eq(assistantIngressMembers.id, memberId))
+    .get();
+
+  return updated ? rowToMember(updated) : null;
+}
+
+// ---------------------------------------------------------------------------
+// findMember
+// ---------------------------------------------------------------------------
+
+export function findMember(params: {
+  assistantId?: string;
+  sourceChannel: string;
+  externalUserId?: string;
+  externalChatId?: string;
+}): IngressMember | null {
+  if (!params.externalUserId && !params.externalChatId) {
+    return null;
+  }
+
+  const db = getDb();
+  const assistantId = params.assistantId ?? 'self';
+
+  // Prefer lookup by externalUserId when available, fall back to externalChatId
+  const matchConditions = [];
+  if (params.externalUserId) {
+    matchConditions.push(
+      and(
+        eq(assistantIngressMembers.assistantId, assistantId),
+        eq(assistantIngressMembers.sourceChannel, params.sourceChannel),
+        eq(assistantIngressMembers.externalUserId, params.externalUserId),
+      ),
+    );
+  }
+  if (params.externalChatId) {
+    matchConditions.push(
+      and(
+        eq(assistantIngressMembers.assistantId, assistantId),
+        eq(assistantIngressMembers.sourceChannel, params.sourceChannel),
+        eq(assistantIngressMembers.externalChatId, params.externalChatId),
+      ),
+    );
+  }
+
+  const row = db
+    .select()
+    .from(assistantIngressMembers)
+    .where(matchConditions.length === 1 ? matchConditions[0] : or(...matchConditions))
+    .get();
+
+  return row ? rowToMember(row) : null;
+}
+
+// ---------------------------------------------------------------------------
+// updateLastSeen
+// ---------------------------------------------------------------------------
+
+export function updateLastSeen(memberId: string): void {
+  const db = getDb();
+  const now = Date.now();
+
+  db.update(assistantIngressMembers)
+    .set({ lastSeenAt: now, updatedAt: now })
+    .where(eq(assistantIngressMembers.id, memberId))
+    .run();
+}