@growth-labs/cms 0.5.1 → 0.5.3

package/dist/ui/screens/subscriptions-data.d.ts

@@ -0,0 +1,33 @@
+import type { ComplimentaryAccessPage, ComplimentaryEmailRetryResult, ComplimentaryEntitlementRow, ComplimentaryGrantResult, ComplimentaryRevokeResult, ProviderResult } from '../../providers/types.js';
+export interface ComplimentaryGrantForm {
+    email: string;
+    reason: string;
+}
+export interface ResultCopy {
+    tone: 'success' | 'warning' | 'info' | 'error';
+    message: string;
+}
+export declare function buildComplimentaryGrantPayload(form: ComplimentaryGrantForm): {
+    email: string;
+    reason: string;
+};
+export declare function buildComplimentaryRevokePayload(entitlement: Pick<ComplimentaryEntitlementRow, 'id'>, reason: string): {
+    entitlementId: string;
+    reason: string;
+};
+export declare function buildComplimentaryRetryPayload(entitlement: Pick<ComplimentaryEntitlementRow, 'id'>, reason: string): {
+    entitlementId: string;
+    reason: string;
+};
+export declare function complimentaryGrantSubmitDisabled(form: ComplimentaryGrantForm, submitting: boolean): boolean;
+export declare function describeComplimentaryGrantResult(result: ProviderResult<ComplimentaryGrantResult>): ResultCopy;
+export declare function describeComplimentaryRevokeResult(result: ProviderResult<ComplimentaryRevokeResult>): ResultCopy;
+export declare function describeComplimentaryRetryResult(result: ProviderResult<ComplimentaryEmailRetryResult>): ResultCopy;
+export declare function complimentaryRowActions(row: ComplimentaryEntitlementRow, nowUnixSeconds?: number): {
+    canRevoke: boolean;
+    canRetryEmail: boolean;
+    retryLabel: string;
+};
+export declare function complimentaryPageLabel(page: ComplimentaryAccessPage): string;
+export declare function formatTimestamp(value: number): string;
+//# sourceMappingURL=subscriptions-data.d.ts.map

package/dist/ui/screens/subscriptions-data.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"subscriptions-data.d.ts","sourceRoot":"","sources":["../../../src/ui/screens/subscriptions-data.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACX,uBAAuB,EACvB,6BAA6B,EAC7B,2BAA2B,EAC3B,wBAAwB,EACxB,yBAAyB,EACzB,cAAc,EACd,MAAM,0BAA0B,CAAA;AAGjC,MAAM,WAAW,sBAAsB;IACtC,KAAK,EAAE,MAAM,CAAA;IACb,MAAM,EAAE,MAAM,CAAA;CACd;AAED,MAAM,WAAW,UAAU;IAC1B,IAAI,EAAE,SAAS,GAAG,SAAS,GAAG,MAAM,GAAG,OAAO,CAAA;IAC9C,OAAO,EAAE,MAAM,CAAA;CACf;AAED,wBAAgB,8BAA8B,CAAC,IAAI,EAAE,sBAAsB;;;EAK1E;AAED,wBAAgB,+BAA+B,CAC9C,WAAW,EAAE,IAAI,CAAC,2BAA2B,EAAE,IAAI,CAAC,EACpD,MAAM,EAAE,MAAM;;;EAMd;AAED,wBAAgB,8BAA8B,CAC7C,WAAW,EAAE,IAAI,CAAC,2BAA2B,EAAE,IAAI,CAAC,EACpD,MAAM,EAAE,MAAM;;;EAMd;AAED,wBAAgB,gCAAgC,CAC/C,IAAI,EAAE,sBAAsB,EAC5B,UAAU,EAAE,OAAO,GACjB,OAAO,CAET;AAED,wBAAgB,gCAAgC,CAC/C,MAAM,EAAE,cAAc,CAAC,wBAAwB,CAAC,GAC9C,UAAU,CAoCZ;AAED,wBAAgB,iCAAiC,CAChD,MAAM,EAAE,cAAc,CAAC,yBAAyB,CAAC,GAC/C,UAAU,CAQZ;AAED,wBAAgB,gCAAgC,CAC/C,MAAM,EAAE,cAAc,CAAC,6BAA6B,CAAC,GACnD,UAAU,CA0BZ;AAED,wBAAgB,uBAAuB,CACtC,GAAG,EAAE,2BAA2B,EAChC,cAAc,SAAgC;;;;EAwB9C;AAED,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,uBAAuB,GAAG,MAAM,CAE5E;AAED,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAOrD"}

package/dist/ui/screens/subscriptions-data.js

@@ -0,0 +1,143 @@
+import { MAX_COMPLIMENTARY_UNIX_SECONDS } from '../../providers/types.js';
+export function buildComplimentaryGrantPayload(form) {
+    return {
+        email: form.email.trim().toLowerCase(),
+        reason: form.reason.trim(),
+    };
+}
+export function buildComplimentaryRevokePayload(entitlement, reason) {
+    return {
+        entitlementId: entitlement.id,
+        reason: reason.trim(),
+    };
+}
+export function buildComplimentaryRetryPayload(entitlement, reason) {
+    return {
+        entitlementId: entitlement.id,
+        reason: reason.trim(),
+    };
+}
+export function complimentaryGrantSubmitDisabled(form, submitting) {
+    return submitting || form.email.trim().length === 0 || form.reason.trim().length === 0;
+}
+export function describeComplimentaryGrantResult(result) {
+    if (result.status === 'empty') {
+        return { tone: 'error', message: 'Complimentary access provider is not configured.' };
+    }
+    if (result.data.outcome === 'already_active') {
+        return {
+            tone: 'info',
+            message: 'Complimentary access was already active. No new email was sent.',
+        };
+    }
+    switch (result.data.email.status) {
+        case 'sent':
+            return { tone: 'success', message: 'Access granted and email sent.' };
+        case 'failed':
+            return {
+                tone: 'warning',
+                message: 'Access granted, but the email failed. Retry delivery from the row action.',
+            };
+        case 'unknown':
+            return {
+                tone: 'warning',
+                message: 'Access granted, but email delivery is unknown. Retry delivery from the row action.',
+            };
+        case 'pending':
+        case 'sending':
+            return {
+                tone: 'info',
+                message: 'Access granted and email delivery is in progress.',
+            };
+        case 'not_attempted':
+            return {
+                tone: 'warning',
+                message: 'Access granted, but no email attempt was recorded.',
+            };
+    }
+}
+export function describeComplimentaryRevokeResult(result) {
+    if (result.status === 'empty') {
+        return { tone: 'error', message: 'Complimentary access provider is not configured.' };
+    }
+    if (result.data.outcome === 'already_revoked') {
+        return { tone: 'info', message: 'Complimentary access was already revoked.' };
+    }
+    return { tone: 'success', message: 'Complimentary access revoked.' };
+}
+export function describeComplimentaryRetryResult(result) {
+    if (result.status === 'empty') {
+        return { tone: 'error', message: 'Complimentary access provider is not configured.' };
+    }
+    if (result.data.outcome === 'throttled') {
+        return {
+            tone: 'warning',
+            message: `Retry is not eligible yet.${eligibleSuffix(result.data.email.nextEligibleAt)}`,
+        };
+    }
+    if (result.data.outcome === 'conflict') {
+        return { tone: 'warning', message: 'Another email delivery is already in progress.' };
+    }
+    switch (result.data.email.status) {
+        case 'sent':
+            return { tone: 'success', message: 'Email resent.' };
+        case 'failed':
+            return { tone: 'warning', message: 'Email retry failed. Access remains active.' };
+        case 'unknown':
+            return { tone: 'warning', message: 'Email retry outcome is unknown. Access remains active.' };
+        case 'pending':
+        case 'sending':
+            return { tone: 'info', message: 'Email retry is in progress.' };
+        case 'not_attempted':
+            return { tone: 'info', message: 'No email retry was attempted.' };
+    }
+}
+export function complimentaryRowActions(row, nowUnixSeconds = Math.floor(Date.now() / 1000)) {
+    const active = row.revokedAt === null;
+    const nextEligibleAt = row.emailNextEligibleAt;
+    const nextEligibleAtValid = nextEligibleAt === null || isRenderableUnixSeconds(nextEligibleAt);
+    const retryWindowElapsed = nextEligibleAt === null || (nextEligibleAtValid && nextEligibleAt <= nowUnixSeconds);
+    const retryLabel = nextEligibleAt === null || retryWindowElapsed
+        ? 'Retry email'
+        : nextEligibleAtValid
+            ? `Retry after ${formatTimestamp(nextEligibleAt)}`
+            : 'Retry timing unavailable';
+    const canRetryEmail = active &&
+        row.emailRetryable &&
+        (row.emailStatus === 'failed' || row.emailStatus === 'unknown') &&
+        nextEligibleAtValid &&
+        retryWindowElapsed;
+    return {
+        canRevoke: active,
+        canRetryEmail,
+        retryLabel,
+    };
+}
+export function complimentaryPageLabel(page) {
+    return `Page ${page.page} of ${page.totalPages} · ${page.total.toLocaleString('en-US')} records`;
+}
+export function formatTimestamp(value) {
+    if (!isRenderableUnixSeconds(value))
+        return 'Date unavailable';
+    try {
+        return new Date(value * 1000).toISOString().slice(0, 16).replace('T', ' ');
+    }
+    catch {
+        return 'Date unavailable';
+    }
+}
+function eligibleSuffix(nextEligibleAt) {
+    if (nextEligibleAt === null)
+        return '';
+    const formatted = formatTimestamp(nextEligibleAt);
+    return formatted === 'Date unavailable'
+        ? ' Retry timing is unavailable.'
+        : ` Try again after ${formatted}.`;
+}
+function isRenderableUnixSeconds(value) {
+    return (Number.isInteger(value) &&
+        value >= 0 &&
+        value <= MAX_COMPLIMENTARY_UNIX_SECONDS &&
+        Number.isSafeInteger(value * 1000));
+}
+//# sourceMappingURL=subscriptions-data.js.map

package/dist/ui/screens/subscriptions-data.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"subscriptions-data.js","sourceRoot":"","sources":["../../../src/ui/screens/subscriptions-data.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@growth-labs/cms",
-  "version": "0.5.1",
+  "version": "0.5.3",
   "type": "module",
   "bin": {
     "growth-labs-cms-migrations": "./dist/cli/migrations.js"

package/src/engine/publisher.ts

@@ -471,23 +471,29 @@ async function ensureTags(db: D1Database, tags: string[]): Promise<{ id: string;
 	const results: { id: string; slug: string }[] = []
 
 	for (const tag of normalized) {
-		const existing = await db
+		// Concurrency-safe upsert. A plain SELECT-then-INSERT races under parallel
+		// import shards: two shards can both miss the same shared tag slug and both
+		// INSERT it, and the second hits `UNIQUE constraint failed: content_tags.slug`
+		// (packages#320). `ON CONFLICT(slug) DO NOTHING` makes the insert idempotent —
+		// exactly one row wins, the loser is a no-op — then a single SELECT resolves
+		// the winning row's id (ours or the concurrent shard's). content_tag_links is
+		// keyed by tag_id, so shards converging on one shared tag id is correct.
+		await db
+			.prepare(
+				'INSERT INTO content_tags (id, slug, label) VALUES (?, ?, ?) ON CONFLICT(slug) DO NOTHING',
+			)
+			.bind(crypto.randomUUID(), tag, tag)
+			.run()
+
+		const row = await db
 			.prepare('SELECT id, slug FROM content_tags WHERE slug = ? LIMIT 1')
 			.bind(tag)
 			.first<{ id: string; slug: string }>()
 
-		if (existing) {
-			results.push(existing)
-			continue
+		if (!row) {
+			throw new Error(`content tag "${tag}" could not be resolved after upsert`)
 		}
-
-		const id = crypto.randomUUID()
-		await db
-			.prepare('INSERT INTO content_tags (id, slug, label) VALUES (?, ?, ?)')
-			.bind(id, tag, tag)
-			.run()
-
-		results.push({ id, slug: tag })
+		results.push(row)
 	}
 
 	return results

package/src/providers/null.ts

@@ -8,6 +8,7 @@ import type {
 	SettingsProvider,
 	SubscriptionsProvider,
 } from './types.js'
+import { ProviderHttpError } from './types.js'
 
 const empty = <T>(data: T) => ({ status: 'empty' as const, data })
 
@@ -77,9 +78,6 @@ export const nullSubscriptions: SubscriptionsProvider = {
 	async exportMembers() {
 		return empty('')
 	},
-	async createGift() {
-		return empty({ id: '' })
-	},
 	async detectDuplicates() {
 		return empty({
 			billingConflicts: [],
@@ -111,6 +109,37 @@ export const nullSubscriptions: SubscriptionsProvider = {
 			summary: { redeemed: 0, pendingClaim: 0 },
 		})
 	},
+	async listComplimentaryAccess(query) {
+		return empty({
+			rows: [],
+			total: 0,
+			page: query.page,
+			pageSize: query.pageSize,
+			totalPages: 0,
+			summary: { active: 0, revoked: 0, failedEmail: 0, unknownEmail: 0, notAttempted: 0 },
+		})
+	},
+	async grantComplimentaryAccess() {
+		throw new ProviderHttpError(
+			501,
+			'complimentary_provider_unavailable',
+			'Complimentary access provider not configured',
+		)
+	},
+	async revokeComplimentaryAccess() {
+		throw new ProviderHttpError(
+			501,
+			'complimentary_provider_unavailable',
+			'Complimentary access provider not configured',
+		)
+	},
+	async retryComplimentaryAccessEmail() {
+		throw new ProviderHttpError(
+			501,
+			'complimentary_provider_unavailable',
+			'Complimentary access provider not configured',
+		)
+	},
 }
 
 export const nullIdentity: IdentityProvider = {

package/src/providers/types.ts

@@ -182,6 +182,121 @@ export interface GiftOrdersPage {
 	}
 }
 
+export interface ProviderHttpErrorBody {
+	error: string
+	code: string
+	nextEligibleAt?: number | null
+}
+
+export class ProviderHttpError extends Error {
+	readonly status: number
+	readonly code: string
+	readonly nextEligibleAt: number | null
+
+	constructor(status: number, code: string, message: string, nextEligibleAt: number | null = null) {
+		super(message)
+		this.name = 'ProviderHttpError'
+		this.status = status
+		this.code = code
+		this.nextEligibleAt = nextEligibleAt
+	}
+
+	toBody(): ProviderHttpErrorBody {
+		return {
+			error: this.message,
+			code: this.code,
+			...(this.nextEligibleAt === null ? {} : { nextEligibleAt: this.nextEligibleAt }),
+		}
+	}
+}
+
+export type ComplimentaryDeliveryStatus = 'pending' | 'sending' | 'sent' | 'failed' | 'unknown'
+export type ComplimentaryEmailStatus = ComplimentaryDeliveryStatus | 'not_attempted'
+export type ComplimentaryEntitlementStatusFilter = 'active' | 'revoked' | 'all'
+export const MAX_COMPLIMENTARY_UNIX_SECONDS = 253_402_300_799
+
+export interface ComplimentaryEntitlementRow {
+	id: string
+	userId: string
+	email: string
+	grantReason: string
+	grantedAt: number
+	grantedBySubject: string
+	revokedAt: number | null
+	revokedBySubject: string | null
+	revokeReason: string | null
+	emailStatus: ComplimentaryEmailStatus
+	emailAttemptCount: number
+	emailRetryable: boolean
+	emailNextEligibleAt: number | null
+}
+
+export interface ComplimentaryAccessQuery {
+	q?: string
+	status: ComplimentaryEntitlementStatusFilter
+	page: number
+	pageSize: number
+}
+
+export interface ComplimentaryAccessPage {
+	rows: ComplimentaryEntitlementRow[]
+	total: number
+	page: number
+	pageSize: number
+	totalPages: number
+	summary: {
+		active: number
+		revoked: number
+		failedEmail: number
+		unknownEmail: number
+		notAttempted: number
+	}
+}
+
+export interface TrustedActor {
+	subject: string
+}
+
+export interface ComplimentaryGrantInput {
+	email: string
+	reason: string
+}
+
+export interface ComplimentaryGrantResult {
+	outcome: 'created' | 'already_active'
+	entitlement: ComplimentaryEntitlementRow
+	email: {
+		status: ComplimentaryEmailStatus
+		retryable: boolean
+		nextEligibleAt: number | null
+	}
+}
+
+export interface ComplimentaryRevokeInput {
+	entitlementId: string
+	reason: string
+}
+
+export interface ComplimentaryRevokeResult {
+	outcome: 'revoked' | 'already_revoked'
+	entitlement: ComplimentaryEntitlementRow
+}
+
+export interface ComplimentaryEmailRetryInput {
+	entitlementId: string
+	reason: string
+}
+
+export interface ComplimentaryEmailRetryResult {
+	outcome: 'queued' | 'sent' | 'failed' | 'unknown' | 'throttled' | 'conflict'
+	entitlement: ComplimentaryEntitlementRow
+	email: {
+		status: ComplimentaryEmailStatus
+		retryable: boolean
+		nextEligibleAt: number | null
+	}
+}
+
 export interface SubscriptionsProvider {
 	listMembers(
 		filter: Record<string, string | undefined>,
@@ -191,10 +306,6 @@ export interface SubscriptionsProvider {
 	getPlanMix(): Promise<ProviderResult<Array<{ plan: string; count: number }>>>
 	resolvePlanName(variantId: string): string
 	exportMembers(fmt: 'csv' | 'json'): Promise<ProviderResult<string>>
-	createGift(input: {
-		email: string
-		planVariantId: string
-	}): Promise<ProviderResult<{ id: string }>>
 	/**
 	 * Detect accounts that collide on billing email or canonical (gmail-folded)
 	 * email — READ-only. Legacy: GET /admin/api/duplicate-accounts.
@@ -211,6 +322,25 @@ export interface SubscriptionsProvider {
 	 * Legacy: GET /admin/api/gifts.
 	 */
 	listGifts(query: GiftOrdersQuery): Promise<ProviderResult<GiftOrdersPage>>
+	/** List current and historical complimentary access records. */
+	listComplimentaryAccess(
+		query: ComplimentaryAccessQuery,
+	): Promise<ProviderResult<ComplimentaryAccessPage>>
+	/** Grant complimentary access; the trusted actor is route-derived, never client-provided. */
+	grantComplimentaryAccess(
+		input: ComplimentaryGrantInput,
+		actor: TrustedActor,
+	): Promise<ProviderResult<ComplimentaryGrantResult>>
+	/** Revoke complimentary access; idempotent for already-revoked entitlements. */
+	revokeComplimentaryAccess(
+		input: ComplimentaryRevokeInput,
+		actor: TrustedActor,
+	): Promise<ProviderResult<ComplimentaryRevokeResult>>
+	/** Retry the stored recipient's complimentary-access email; recipient email is not accepted. */
+	retryComplimentaryAccessEmail(
+		input: ComplimentaryEmailRetryInput,
+		actor: TrustedActor,
+	): Promise<ProviderResult<ComplimentaryEmailRetryResult>>
 }
 
 /** Thin identity seam — the CMS never mints identity (spec §3.3/§12). */

package/src/routes/authz-matrix.ts

@@ -45,6 +45,7 @@ export type { Capability }
 //     publish_others_draft, edit_own_draft (+ media_pipeline; producer too).
 //   senior_editor + owner (NOT editor): manage_team (members/invites),
 //     manage_api_keys, manage_webhooks, export_subscribers (PII).
+//   owner + senior_editor + editor: manage_complimentary_access.
 //   owner ONLY: manage_settings — workspace settings PATCH + the privileged
 //     LemonSqueezy entitlement sync (importLsEntitlements). Matches the 448e815
 //     gate (requireRole('manage_settings')).
@@ -71,6 +72,9 @@ export const CAPABILITY_MATRIX: Record<Capability, ReadonlySet<CmsRole>> = {
 	// Subscriber-PII export: owner + senior_editor only (NOT editor). Editors keep
 	// full editorial but never touch subscriber email lists.
 	export_subscribers: new Set<CmsRole>(['owner', 'senior_editor']),
+	// Complimentary access is an editorial admin action by explicit operator
+	// decision; it is not subscriber-PII export or owner-only settings.
+	manage_complimentary_access: new Set<CmsRole>(['owner', 'senior_editor', 'editor']),
 }
 
 // ---------------------------------------------------------------------------

package/src/routes/context.ts

@@ -35,6 +35,9 @@ export type Capability =
 	// Subscriber-PII export (CSV/JSON of member emails). Gated to owner +
 	// senior_editor — NOT editor (editors keep full editorial but no PII).
 	| 'export_subscribers'
+	// Complimentary access administration. Explicit operator decision: owner,
+	// senior_editor, and editor may grant/revoke/retry; contributor/producer may not.
+	| 'manage_complimentary_access'
 
 export interface CmsUser {
 	subject: string