Skip to content

armgit / papra

Public Imported from GitHub
0

The minimalistic document archiving platform.

feat(plan): add user plan entitlements system (#1161)

Corentin Thomassetbefa9c588034
diff --git a/apps/papra-client/src/modules/ui/layouts/organization.layout.tsx b/apps/papra-client/src/modules/ui/layouts/organization.layout.tsx
index 4bc423c4..b0c51c50 100644
--- a/apps/papra-client/src/modules/ui/layouts/organization.layout.tsx
+++ b/apps/papra-client/src/modules/ui/layouts/organization.layout.tsx
@@ -27,7 +27,7 @@ import {
SelectValue,
} from '../components/select';
import { SidenavLayout } from './sidenav.layout';
-import { PLAN_IDS } from '@papra/app-server/plans/constants';
+import { FREE_PLANS_IDS } from '@papra/app-server/plans/constants';
const UpgradeCTAFooter: Component<{ organizationId: string }> = (props) => {
const { t } = useI18n();
@@ -43,7 +43,9 @@ const UpgradeCTAFooter: Component<{ organizationId: string }> = (props) => {
return false;
}
- return query.data && query.data.plan.id === PLAN_IDS.FREE;
+ return (
+ query.data && FREE_PLANS_IDS.includes(query.data.plan.id as (typeof FREE_PLANS_IDS)[number])
+ );
};
return (
diff --git a/apps/papra-server/src/migrations/list/0024-user-plan-entitlements.migration.ts b/apps/papra-server/src/migrations/list/0024-user-plan-entitlements.migration.ts
new file mode 100644
index 00000000..ecd5a88f
--- /dev/null
+++ b/apps/papra-server/src/migrations/list/0024-user-plan-entitlements.migration.ts
@@ -0,0 +1,30 @@
+import type { Migration } from '../migrations.types';
+import { sql } from 'drizzle-orm';
+
+export const userPlanEntitlementsMigration = {
+ name: 'user-plan-entitlements',
+
+ up: async ({ db }) => {
+ await db.batch([
+ db.run(sql`CREATE TABLE IF NOT EXISTS "user_plan_entitlements" (
+ "id" text PRIMARY KEY NOT NULL,
+ "created_at" integer NOT NULL,
+ "updated_at" integer NOT NULL,
+ "granted_at" integer NOT NULL,
+ "expires_at" integer,
+ "last_verified_at" integer,
+ "user_id" text NOT NULL,
+ "type" text NOT NULL,
+ "source" text NOT NULL,
+ FOREIGN KEY ("user_id") REFERENCES "users"("id") ON UPDATE cascade ON DELETE cascade
+ )`),
+ db.run(
+ sql`CREATE UNIQUE INDEX IF NOT EXISTS "user_plan_entitlements_user_id_type_unique" ON "user_plan_entitlements" ("user_id", "type")`,
+ ),
+ ]);
+ },
+
+ down: async ({ db }) => {
+ await db.run(sql`DROP TABLE IF EXISTS "user_plan_entitlements"`);
+ },
+} satisfies Migration;
diff --git a/apps/papra-server/src/migrations/migrations.registry.test.ts b/apps/papra-server/src/migrations/migrations.registry.test.ts
index 18a3cf3f..e233c342 100644
--- a/apps/papra-server/src/migrations/migrations.registry.test.ts
+++ b/apps/papra-server/src/migrations/migrations.registry.test.ts
@@ -106,6 +106,7 @@ describe('migrations registry', () => {
CREATE INDEX "organizations_deleted_at_purge_at_index" ON "organizations" ("deleted_at","scheduled_purge_at");
CREATE INDEX "organizations_deleted_by_deleted_at_index" ON "organizations" ("deleted_by","deleted_at");
CREATE UNIQUE INDEX tags_organization_id_normalized_name_unique ON tags (organization_id, normalized_name);
+ CREATE UNIQUE INDEX "user_plan_entitlements_user_id_type_unique" ON "user_plan_entitlements" ("user_id", "type");
CREATE INDEX "user_roles_role_index" ON "user_roles" ("role");
CREATE UNIQUE INDEX "user_roles_user_id_role_unique_index" ON "user_roles" ("user_id","role");
CREATE INDEX "users_email_index" ON "users" ("email");
@@ -143,6 +144,7 @@ describe('migrations registry', () => {
CREATE TABLE "tagging_rule_conditions" ( "id" text PRIMARY KEY NOT NULL, "created_at" integer NOT NULL, "updated_at" integer NOT NULL, "tagging_rule_id" text NOT NULL, "field" text NOT NULL, "operator" text NOT NULL, "value" text NOT NULL, "is_case_sensitive" integer DEFAULT false NOT NULL, FOREIGN KEY ("tagging_rule_id") REFERENCES "tagging_rules"("id") ON UPDATE cascade ON DELETE cascade );
CREATE TABLE "tagging_rules" ( "id" text PRIMARY KEY NOT NULL, "created_at" integer NOT NULL, "updated_at" integer NOT NULL, "organization_id" text NOT NULL, "name" text NOT NULL, "description" text, "enabled" integer DEFAULT true NOT NULL, "condition_match_mode" text DEFAULT 'all' NOT NULL, FOREIGN KEY ("organization_id") REFERENCES "organizations"("id") ON UPDATE cascade ON DELETE cascade );
CREATE TABLE "tags" ( "id" text PRIMARY KEY NOT NULL, "created_at" integer NOT NULL, "updated_at" integer NOT NULL, "organization_id" text NOT NULL, "name" text NOT NULL, "color" text NOT NULL, "description" text, "normalized_name" text, FOREIGN KEY ("organization_id") REFERENCES "organizations"("id") ON UPDATE cascade ON DELETE cascade );
+ CREATE TABLE "user_plan_entitlements" ( "id" text PRIMARY KEY NOT NULL, "created_at" integer NOT NULL, "updated_at" integer NOT NULL, "granted_at" integer NOT NULL, "expires_at" integer, "last_verified_at" integer, "user_id" text NOT NULL, "type" text NOT NULL, "source" text NOT NULL, FOREIGN KEY ("user_id") REFERENCES "users"("id") ON UPDATE cascade ON DELETE cascade );
CREATE TABLE "user_roles" ( "id" text PRIMARY KEY NOT NULL, "created_at" integer NOT NULL, "updated_at" integer NOT NULL, "user_id" text NOT NULL, "role" text NOT NULL, FOREIGN KEY ("user_id") REFERENCES "users"("id") ON UPDATE cascade ON DELETE cascade );
CREATE TABLE "users" ( "id" text PRIMARY KEY NOT NULL, "created_at" integer NOT NULL, "updated_at" integer NOT NULL, "email" text NOT NULL, "email_verified" integer DEFAULT false NOT NULL, "name" text, "image" text, "max_organization_count" integer , "two_factor_enabled" integer DEFAULT false NOT NULL);
CREATE TABLE "webhook_deliveries" ( "id" text PRIMARY KEY NOT NULL, "created_at" integer NOT NULL, "updated_at" integer NOT NULL, "webhook_id" text NOT NULL, "event_name" text NOT NULL, "request_payload" text NOT NULL, "response_payload" text NOT NULL, "response_status" integer NOT NULL, FOREIGN KEY ("webhook_id") REFERENCES "webhooks"("id") ON UPDATE cascade ON DELETE cascade );
diff --git a/apps/papra-server/src/migrations/migrations.registry.ts b/apps/papra-server/src/migrations/migrations.registry.ts
index 76f56eb8..d4d39f4c 100644
--- a/apps/papra-server/src/migrations/migrations.registry.ts
+++ b/apps/papra-server/src/migrations/migrations.registry.ts
@@ -23,6 +23,7 @@ import { kvStoreMigration } from './list/0020-kv-store.migration';
import { documentShareLinksMigration } from './list/0021-document-share-links.migration';
import { documentsNotesMigration } from './list/0022-documents-notes.migration';
import { documentViewsMigration } from './list/0023-document-views.migration';
+import { userPlanEntitlementsMigration } from './list/0024-user-plan-entitlements.migration';
export const migrations: Migration[] = [
initialSchemaSetupMigration,
@@ -48,4 +49,5 @@ export const migrations: Migration[] = [
documentShareLinksMigration,
documentsNotesMigration,
documentViewsMigration,
+ userPlanEntitlementsMigration,
];
diff --git a/apps/papra-server/src/modules/app/database/database.test-utils.ts b/apps/papra-server/src/modules/app/database/database.test-utils.ts
index c65424bf..ae16c61a 100644
--- a/apps/papra-server/src/modules/app/database/database.test-utils.ts
+++ b/apps/papra-server/src/modules/app/database/database.test-utils.ts
@@ -32,6 +32,7 @@ import {
} from '../../webhooks/webhooks.tables';
import { accountsTable, sessionsTable, twoFactorTable } from '../auth/auth.tables';
import { setupDatabase } from './database';
+import { planEntitlementsTable } from '../../plan-entitlements/plan-entitlements.tables';
export { createInMemoryDatabase, seedDatabase };
@@ -68,6 +69,7 @@ const seedTables = {
organizationMembers: organizationMembersTable,
organizations: organizationsTable,
organizationSubscriptions: organizationSubscriptionsTable,
+ planEntitlements: planEntitlementsTable,
sessions: sessionsTable,
taggingRuleActions: taggingRuleActionsTable,
taggingRuleConditions: taggingRuleConditionsTable,
diff --git a/apps/papra-server/src/modules/app/server.test-utils.ts b/apps/papra-server/src/modules/app/server.test-utils.ts
index f5ab0bf7..27d46772 100644
--- a/apps/papra-server/src/modules/app/server.test-utils.ts
+++ b/apps/papra-server/src/modules/app/server.test-utils.ts
@@ -17,6 +17,7 @@ import { setupDatabase } from './database/database';
import { registerEventHandlers } from './events/events.handlers';
import { createEventServices } from './events/events.services';
import { createGracefulShutdownService } from './graceful-shutdown/graceful-shutdown.services';
+import { createPlanEntitlementDefinitionRegistry } from '../plan-entitlements/plan-entitlements.registry';
export function createTestServerDependencies(
overrides: Partial<GlobalDependencies> = {},
@@ -45,6 +46,7 @@ export function createTestServerDependencies(
webhookRepository: createWebhookRepository({ db }),
});
const kvStore = overrides.kvStore ?? createKvStore({ driver: createInMemoryKvStoreDriver() });
+ const planEntitlementDefinitionRegistry = createPlanEntitlementDefinitionRegistry({ config });
registerEventHandlers({
eventServices,
@@ -69,5 +71,6 @@ export function createTestServerDependencies(
documentSearchServices,
webhookTriggerServices,
kvStore,
+ planEntitlementDefinitionRegistry,
};
}
diff --git a/apps/papra-server/src/modules/app/server.types.ts b/apps/papra-server/src/modules/app/server.types.ts
index b556c89f..1b018560 100644
--- a/apps/papra-server/src/modules/app/server.types.ts
+++ b/apps/papra-server/src/modules/app/server.types.ts
@@ -14,6 +14,7 @@ import type { Session } from './auth/auth.types';
import type { Database } from './database/database.types';
import type { EventServices } from './events/events.services';
import type { ShutdownServices } from './graceful-shutdown/graceful-shutdown.services';
+import type { PlanEntitlementDefinitionRegistry } from '../plan-entitlements/plan-entitlements.registry';
export type ServerInstanceGenerics = {
Variables: {
@@ -41,6 +42,7 @@ export type GlobalDependencies = {
eventServices: EventServices;
shutdownServices: ShutdownServices;
webhookTriggerServices: WebhookTriggerServices;
+ planEntitlementDefinitionRegistry: PlanEntitlementDefinitionRegistry;
kvStore: KvStore;
};
diff --git a/apps/papra-server/src/modules/config/config.ts b/apps/papra-server/src/modules/config/config.ts
index 674a9c7d..5678b1c0 100644
--- a/apps/papra-server/src/modules/config/config.ts
+++ b/apps/papra-server/src/modules/config/config.ts
@@ -37,6 +37,7 @@ import {
urlSchema,
} from './config.schemas';
import { getCommitInfo } from './config.usecases';
+import { planEntitlementsConfig } from '../plan-entitlements/plan-entitlements.config';
export const configDefinition = {
env: {
@@ -171,6 +172,7 @@ export const configDefinition = {
tracking: trackingConfig,
webhooks: webhookConfig,
kvStore: kvStoreConfig,
+ planEntitlements: planEntitlementsConfig,
} as const satisfies AppConfigDefinition;
const logger = createLogger({ namespace: 'config' });
diff --git a/apps/papra-server/src/modules/documents/documents.routes.ts b/apps/papra-server/src/modules/documents/documents.routes.ts
index 1802063b..67e072af 100644
--- a/apps/papra-server/src/modules/documents/documents.routes.ts
+++ b/apps/papra-server/src/modules/documents/documents.routes.ts
@@ -7,6 +7,7 @@ import { createCustomPropertiesRepository } from '../custom-properties/custom-pr
import { organizationIdSchema } from '../organizations/organization.schemas';
import { createOrganizationsRepository } from '../organizations/organizations.repository';
import { ensureUserIsInOrganization } from '../organizations/organizations.usecases';
+import { createPlanEntitlementsRepository } from '../plan-entitlements/plan-entitlements.repository';
import { createPlansRepository } from '../plans/plans.repository';
import { getOrganizationPlan } from '../plans/plans.usecases';
import { createQueryPaginationSchemaKeys } from '../shared/schemas/pagination.schemas';
@@ -58,7 +59,7 @@ export function registerDocumentsRoutes(context: RouteDefinitionContext) {
}
function setupCreateDocumentRoute({ app, ...deps }: RouteDefinitionContext) {
- const { config, db } = deps;
+ const { config, db, planEntitlementDefinitionRegistry } = deps;
app.post(
'/api/organizations/:organizationId/documents',
@@ -78,11 +79,14 @@ function setupCreateDocumentRoute({ app, ...deps }: RouteDefinitionContext) {
// Get organization's plan-specific upload limit
const plansRepository = createPlansRepository({ config });
const subscriptionsRepository = createSubscriptionsRepository({ db });
+ const planEntitlementsRepository = createPlanEntitlementsRepository({ db });
const { organizationPlan } = await getOrganizationPlan({
organizationId,
plansRepository,
subscriptionsRepository,
+ planEntitlementsRepository,
+ planEntitlementDefinitionRegistry,
});
const { maxFileSize } = organizationPlan.limits;
diff --git a/apps/papra-server/src/modules/documents/documents.usecases.ts b/apps/papra-server/src/modules/documents/documents.usecases.ts
index 82b52311..1bcf7e05 100644
--- a/apps/papra-server/src/modules/documents/documents.usecases.ts
+++ b/apps/papra-server/src/modules/documents/documents.usecases.ts
@@ -4,6 +4,8 @@ import type { Database } from '../app/database/database.types';
import type { EventServices } from '../app/events/events.services';
import type { Config } from '../config/config.types';
import type { CustomPropertiesRepository } from '../custom-properties/custom-properties.repository';
+import type { PlanEntitlementsRepository } from '../plan-entitlements/plan-entitlements.repository';
+import type { PlanEntitlementDefinitionRegistry } from '../plan-entitlements/plan-entitlements.registry';
import type { PlansRepository } from '../plans/plans.repository';
import type { Logger } from '../shared/logger/logger';
import type { SubscriptionsRepository } from '../subscriptions/subscriptions.repository';
@@ -24,6 +26,8 @@ import pLimit from 'p-limit';
import { buildCustomPropertiesArray } from '../custom-properties/custom-properties.models';
import { createOrganizationDocumentStorageLimitReachedError } from '../organizations/organizations.errors';
import { getOrganizationStorageLimits } from '../organizations/organizations.usecases';
+import { createPlanEntitlementsRepository } from '../plan-entitlements/plan-entitlements.repository';
+import { createPlanEntitlementDefinitionRegistry } from '../plan-entitlements/plan-entitlements.registry';
import { createPlansRepository } from '../plans/plans.repository';
import { createError } from '../shared/errors/errors';
import { createLogger } from '../shared/logger/logger';
@@ -70,6 +74,8 @@ export async function createDocument({
generateDocumentId = generateDocumentIdImpl,
plansRepository,
subscriptionsRepository,
+ planEntitlementsRepository,
+ planEntitlementDefinitionRegistry,
taggingRulesRepository,
tagsRepository,
webhookTriggerServices,
@@ -91,6 +97,8 @@ export async function createDocument({
generateDocumentId?: () => string;
plansRepository: PlansRepository;
subscriptionsRepository: SubscriptionsRepository;
+ planEntitlementsRepository: PlanEntitlementsRepository;
+ planEntitlementDefinitionRegistry: PlanEntitlementDefinitionRegistry;
taggingRulesRepository: TaggingRulesRepository;
tagsRepository: TagsRepository;
webhookTriggerServices: WebhookTriggerServices;
@@ -103,6 +111,8 @@ export async function createDocument({
organizationId,
plansRepository,
subscriptionsRepository,
+ planEntitlementsRepository,
+ planEntitlementDefinitionRegistry,
documentsRepository,
});
@@ -183,6 +193,8 @@ export async function createDocument({
documentsStorageService,
plansRepository,
subscriptionsRepository,
+ planEntitlementsRepository,
+ planEntitlementDefinitionRegistry,
documentId,
taskServices,
ocrLanguages,
@@ -223,6 +235,11 @@ export function createDocumentCreationUsecase({
plansRepository: initialDeps.plansRepository ?? createPlansRepository({ config }),
subscriptionsRepository:
initialDeps.subscriptionsRepository ?? createSubscriptionsRepository({ db }),
+ planEntitlementsRepository:
+ initialDeps.planEntitlementsRepository ?? createPlanEntitlementsRepository({ db }),
+ planEntitlementDefinitionRegistry:
+ initialDeps.planEntitlementDefinitionRegistry ??
+ createPlanEntitlementDefinitionRegistry({ config }),
taggingRulesRepository:
initialDeps.taggingRulesRepository ?? createTaggingRulesRepository({ db }),
tagsRepository: initialDeps.tagsRepository ?? createTagsRepository({ db }),
@@ -321,6 +338,8 @@ async function createNewDocument({
organizationId,
plansRepository,
subscriptionsRepository,
+ planEntitlementsRepository,
+ planEntitlementDefinitionRegistry,
documentsRepository,
documentsStorageService,
newFileStorageContext,
@@ -341,6 +360,8 @@ async function createNewDocument({
documentsStorageService: DocumentStorageService;
plansRepository: PlansRepository;
subscriptionsRepository: SubscriptionsRepository;
+ planEntitlementsRepository: PlanEntitlementsRepository;
+ planEntitlementDefinitionRegistry: PlanEntitlementDefinitionRegistry;
newFileStorageContext: DocumentStorageContext;
taskServices: TaskServices;
ocrLanguages?: string[];
@@ -354,6 +375,8 @@ async function createNewDocument({
organizationId,
plansRepository,
subscriptionsRepository,
+ planEntitlementsRepository,
+ planEntitlementDefinitionRegistry,
documentsRepository,
});
diff --git a/apps/papra-server/src/modules/intake-emails/intake-emails.routes.ts b/apps/papra-server/src/modules/intake-emails/intake-emails.routes.ts
index 50b30bc6..3c4ea7e0 100644
--- a/apps/papra-server/src/modules/intake-emails/intake-emails.routes.ts
+++ b/apps/papra-server/src/modules/intake-emails/intake-emails.routes.ts
@@ -8,6 +8,7 @@ import { createDocumentCreationUsecase } from '../documents/documents.usecases';
import { organizationIdSchema } from '../organizations/organization.schemas';
import { createOrganizationsRepository } from '../organizations/organizations.repository';
import { ensureUserIsInOrganization } from '../organizations/organizations.usecases';
+import { createPlanEntitlementsRepository } from '../plan-entitlements/plan-entitlements.repository';
import { createPlansRepository } from '../plans/plans.repository';
import { createError } from '../shared/errors/errors';
import { getHeader } from '../shared/headers/headers.models';
@@ -73,7 +74,12 @@ function setupGetOrganizationIntakeEmailsRoute({ app, db }: RouteDefinitionConte
);
}
-function setupCreateIntakeEmailRoute({ app, db, config }: RouteDefinitionContext) {
+function setupCreateIntakeEmailRoute({
+ app,
+ db,
+ config,
+ planEntitlementDefinitionRegistry,
+}: RouteDefinitionContext) {
app.post(
'/api/organizations/:organizationId/intake-emails',
requireAuthentication(),
@@ -92,6 +98,7 @@ function setupCreateIntakeEmailRoute({ app, db, config }: RouteDefinitionContext
const intakeEmailsServices = createIntakeEmailsServices({ config });
const plansRepository = createPlansRepository({ config });
const subscriptionsRepository = createSubscriptionsRepository({ db });
+ const planEntitlementsRepository = createPlanEntitlementsRepository({ db });
const intakeEmailUsernameServices = createIntakeEmailUsernameServices({
config,
usersRepository,
@@ -107,6 +114,8 @@ function setupCreateIntakeEmailRoute({ app, db, config }: RouteDefinitionContext
intakeEmailsServices,
plansRepository,
subscriptionsRepository,
+ planEntitlementsRepository,
+ planEntitlementDefinitionRegistry,
intakeEmailUsernameServices,
});
diff --git a/apps/papra-server/src/modules/intake-emails/intake-emails.usecases.test.ts b/apps/papra-server/src/modules/intake-emails/intake-emails.usecases.test.ts
index 7f78b43b..d3c13d63 100644
--- a/apps/papra-server/src/modules/intake-emails/intake-emails.usecases.test.ts
+++ b/apps/papra-server/src/modules/intake-emails/intake-emails.usecases.test.ts
@@ -8,6 +8,8 @@ import { overrideConfig } from '../config/config.test-utils';
import { documentsTable } from '../documents/documents.table';
import { createDocumentCreationUsecase } from '../documents/documents.usecases';
import { createInMemoryDocumentStorageServices } from '../documents/storage/documents.storage.services.test-utils';
+import { createPlanEntitlementsRepository } from '../plan-entitlements/plan-entitlements.repository';
+import { createPlanEntitlementDefinitionRegistry } from '../plan-entitlements/plan-entitlements.registry';
import { PLAN_IDS } from '../plans/plans.constants';
import { pick } from '../shared/objects';
import { createSubscriptionsRepository } from '../subscriptions/subscriptions.repository';
@@ -322,12 +324,18 @@ describe('intake-emails usecases', () => {
} as unknown as PlansRepository;
const subscriptionsRepository = createSubscriptionsRepository({ db });
+ const planEntitlementsRepository = createPlanEntitlementsRepository({ db });
+ const planEntitlementDefinitionRegistry = createPlanEntitlementDefinitionRegistry({
+ config: overrideConfig(),
+ });
// no throw as the intake email count is less than the allowed limit
await checkIfOrganizationCanCreateNewIntakeEmail({
organizationId: 'org-1',
plansRepository,
subscriptionsRepository,
+ planEntitlementsRepository,
+ planEntitlementDefinitionRegistry,
intakeEmailsRepository,
});
@@ -341,6 +349,8 @@ describe('intake-emails usecases', () => {
organizationId: 'org-1',
plansRepository,
subscriptionsRepository,
+ planEntitlementsRepository,
+ planEntitlementDefinitionRegistry,
intakeEmailsRepository,
}),
).rejects.toThrow(createIntakeEmailLimitReachedError());
diff --git a/apps/papra-server/src/modules/intake-emails/intake-emails.usecases.ts b/apps/papra-server/src/modules/intake-emails/intake-emails.usecases.ts
index d47c3dfa..19baebf5 100644
--- a/apps/papra-server/src/modules/intake-emails/intake-emails.usecases.ts
+++ b/apps/papra-server/src/modules/intake-emails/intake-emails.usecases.ts
@@ -1,4 +1,6 @@
import type { CreateDocumentUsecase } from '../documents/documents.usecases';
+import type { PlanEntitlementsRepository } from '../plan-entitlements/plan-entitlements.repository';
+import type { PlanEntitlementDefinitionRegistry } from '../plan-entitlements/plan-entitlements.registry';
import type { PlansRepository } from '../plans/plans.repository';
import type { Logger } from '../shared/logger/logger';
import type { SubscriptionsRepository } from '../subscriptions/subscriptions.repository';
@@ -23,6 +25,8 @@ export async function createIntakeEmail({
intakeEmailsServices,
plansRepository,
subscriptionsRepository,
+ planEntitlementsRepository,
+ planEntitlementDefinitionRegistry,
intakeEmailUsernameServices,
}: {
userId: string;
@@ -31,12 +35,16 @@ export async function createIntakeEmail({
intakeEmailsServices: IntakeEmailsServices;
plansRepository: PlansRepository;
subscriptionsRepository: SubscriptionsRepository;
+ planEntitlementsRepository: PlanEntitlementsRepository;
+ planEntitlementDefinitionRegistry: PlanEntitlementDefinitionRegistry;
intakeEmailUsernameServices: IntakeEmailUsernameServices;
}) {
await checkIfOrganizationCanCreateNewIntakeEmail({
organizationId,
plansRepository,
subscriptionsRepository,
+ planEntitlementsRepository,
+ planEntitlementDefinitionRegistry,
intakeEmailsRepository,
});
@@ -156,11 +164,15 @@ export async function checkIfOrganizationCanCreateNewIntakeEmail({
organizationId,
plansRepository,
subscriptionsRepository,
+ planEntitlementsRepository,
+ planEntitlementDefinitionRegistry,
intakeEmailsRepository,
}: {
organizationId: string;
plansRepository: PlansRepository;
subscriptionsRepository: SubscriptionsRepository;
+ planEntitlementsRepository: PlanEntitlementsRepository;
+ planEntitlementDefinitionRegistry: PlanEntitlementDefinitionRegistry;
intakeEmailsRepository: IntakeEmailsRepository;
}) {
const { intakeEmailCount } = await intakeEmailsRepository.getOrganizationIntakeEmailsCount({
@@ -170,6 +182,8 @@ export async function checkIfOrganizationCanCreateNewIntakeEmail({
organizationId,
plansRepository,
subscriptionsRepository,
+ planEntitlementsRepository,
+ planEntitlementDefinitionRegistry,
});
if (intakeEmailCount >= organizationPlan.limits.maxIntakeEmailsCount) {
diff --git a/apps/papra-server/src/modules/organizations/organizations.routes.ts b/apps/papra-server/src/modules/organizations/organizations.routes.ts
index 8a718cbc..1d8d34fd 100644
--- a/apps/papra-server/src/modules/organizations/organizations.routes.ts
+++ b/apps/papra-server/src/modules/organizations/organizations.routes.ts
@@ -3,6 +3,7 @@ import * as v from 'valibot';
import { createForbiddenError } from '../app/auth/auth.errors';
import { requireAuthentication } from '../app/auth/auth.middleware';
import { getUser } from '../app/auth/auth.models';
+import { createPlanEntitlementsRepository } from '../plan-entitlements/plan-entitlements.repository';
import { createPlansRepository } from '../plans/plans.repository';
import { validateJsonBody, validateParams } from '../shared/validation/validation';
import { createSubscriptionsRepository } from '../subscriptions/subscriptions.repository';
@@ -329,6 +330,7 @@ function setupInviteOrganizationMemberRoute({
db,
config,
emailsServices,
+ planEntitlementDefinitionRegistry,
}: RouteDefinitionContext) {
app.post(
'/api/organizations/:organizationId/members/invitations',
@@ -352,6 +354,7 @@ function setupInviteOrganizationMemberRoute({
const organizationsRepository = createOrganizationsRepository({ db });
const subscriptionsRepository = createSubscriptionsRepository({ db });
const plansRepository = createPlansRepository({ config });
+ const planEntitlementsRepository = createPlanEntitlementsRepository({ db });
await ensureUserIsInOrganization({ userId, organizationId, organizationsRepository });
@@ -362,6 +365,8 @@ function setupInviteOrganizationMemberRoute({
organizationsRepository,
subscriptionsRepository,
plansRepository,
+ planEntitlementsRepository,
+ planEntitlementDefinitionRegistry,
inviterId: userId,
expirationDelayDays: config.organizations.invitationExpirationDelayDays,
maxInvitationsPerDay: config.organizations.maxUserInvitationsPerDay,
diff --git a/apps/papra-server/src/modules/organizations/organizations.usecases.test.ts b/apps/papra-server/src/modules/organizations/organizations.usecases.test.ts
index 369e0834..cfe894e9 100644
--- a/apps/papra-server/src/modules/organizations/organizations.usecases.test.ts
+++ b/apps/papra-server/src/modules/organizations/organizations.usecases.test.ts
@@ -7,6 +7,8 @@ import { createForbiddenError } from '../app/auth/auth.errors';
import { createInMemoryDatabase } from '../app/database/database.test-utils';
import { overrideConfig } from '../config/config.test-utils';
import { createDocumentsRepository } from '../documents/documents.repository';
+import { createPlanEntitlementsRepository } from '../plan-entitlements/plan-entitlements.repository';
+import { createPlanEntitlementDefinitionRegistry } from '../plan-entitlements/plan-entitlements.registry';
import { createTestLogger } from '../shared/logger/logger.test-utils';
import { createSubscriptionsRepository } from '../subscriptions/subscriptions.repository';
import { createUsersRepository } from '../users/users.repository';
@@ -496,6 +498,8 @@ describe('organizations usecases', () => {
organizationsRepository,
subscriptionsRepository,
plansRepository,
+ planEntitlementsRepository: createPlanEntitlementsRepository({ db }),
+ planEntitlementDefinitionRegistry: createPlanEntitlementDefinitionRegistry({ config }),
inviterId: 'user-1',
expirationDelayDays: 7,
maxInvitationsPerDay: 10,
@@ -513,6 +517,8 @@ describe('organizations usecases', () => {
organizationsRepository,
subscriptionsRepository,
plansRepository,
+ planEntitlementsRepository: createPlanEntitlementsRepository({ db }),
+ planEntitlementDefinitionRegistry: createPlanEntitlementDefinitionRegistry({ config }),
inviterId: 'user-2',
expirationDelayDays: 7,
maxInvitationsPerDay: 10,
@@ -531,6 +537,8 @@ describe('organizations usecases', () => {
organizationsRepository,
subscriptionsRepository,
plansRepository,
+ planEntitlementsRepository: createPlanEntitlementsRepository({ db }),
+ planEntitlementDefinitionRegistry: createPlanEntitlementDefinitionRegistry({ config }),
inviterId: 'user-3',
expirationDelayDays: 7,
maxInvitationsPerDay: 10,
@@ -590,6 +598,8 @@ describe('organizations usecases', () => {
organizationsRepository,
subscriptionsRepository,
plansRepository,
+ planEntitlementsRepository: createPlanEntitlementsRepository({ db }),
+ planEntitlementDefinitionRegistry: createPlanEntitlementDefinitionRegistry({ config }),
inviterId: 'user-1',
expirationDelayDays: 7,
maxInvitationsPerDay: 10,
@@ -658,6 +668,8 @@ describe('organizations usecases', () => {
organizationsRepository,
subscriptionsRepository,
plansRepository,
+ planEntitlementsRepository: createPlanEntitlementsRepository({ db }),
+ planEntitlementDefinitionRegistry: createPlanEntitlementDefinitionRegistry({ config }),
inviterId: 'user-1',
expirationDelayDays: 7,
maxInvitationsPerDay: 10,
@@ -731,6 +743,8 @@ describe('organizations usecases', () => {
organizationsRepository,
subscriptionsRepository,
plansRepository,
+ planEntitlementsRepository: createPlanEntitlementsRepository({ db }),
+ planEntitlementDefinitionRegistry: createPlanEntitlementDefinitionRegistry({ config }),
inviterId: 'user-1',
expirationDelayDays: 7,
maxInvitationsPerDay: 10,
@@ -802,6 +816,8 @@ describe('organizations usecases', () => {
organizationsRepository,
subscriptionsRepository,
plansRepository,
+ planEntitlementsRepository: createPlanEntitlementsRepository({ db }),
+ planEntitlementDefinitionRegistry: createPlanEntitlementDefinitionRegistry({ config }),
inviterId: 'user-1',
expirationDelayDays: 7,
maxInvitationsPerDay: 10,
@@ -882,6 +898,8 @@ describe('organizations usecases', () => {
organizationsRepository,
subscriptionsRepository,
plansRepository,
+ planEntitlementsRepository: createPlanEntitlementsRepository({ db }),
+ planEntitlementDefinitionRegistry: createPlanEntitlementDefinitionRegistry({ config }),
inviterId: 'user-1',
expirationDelayDays: 7,
maxInvitationsPerDay: 2,
@@ -930,6 +948,8 @@ describe('organizations usecases', () => {
organizationsRepository,
subscriptionsRepository,
plansRepository,
+ planEntitlementsRepository: createPlanEntitlementsRepository({ db }),
+ planEntitlementDefinitionRegistry: createPlanEntitlementDefinitionRegistry({ config }),
inviterId: 'user-1',
expirationDelayDays: 7,
maxInvitationsPerDay: 10,
@@ -1006,6 +1026,8 @@ describe('organizations usecases', () => {
organizationsRepository,
subscriptionsRepository,
plansRepository,
+ planEntitlementsRepository: createPlanEntitlementsRepository({ db }),
+ planEntitlementDefinitionRegistry: createPlanEntitlementDefinitionRegistry({ config }),
inviterId: 'user-2',
expirationDelayDays: 7,
maxInvitationsPerDay: 10,
diff --git a/apps/papra-server/src/modules/organizations/organizations.usecases.ts b/apps/papra-server/src/modules/organizations/organizations.usecases.ts
index 9e485f22..2cdefadc 100644
--- a/apps/papra-server/src/modules/organizations/organizations.usecases.ts
+++ b/apps/papra-server/src/modules/organizations/organizations.usecases.ts
@@ -2,6 +2,8 @@ import type { Config } from '../config/config.types';
import type { DocumentsRepository } from '../documents/documents.repository';
import type { DocumentStorageService } from '../documents/storage/documents.storage.services';
import type { EmailsServices } from '../emails/emails.services';
+import type { PlanEntitlementsRepository } from '../plan-entitlements/plan-entitlements.repository';
+import type { PlanEntitlementDefinitionRegistry } from '../plan-entitlements/plan-entitlements.registry';
import type { PlansRepository } from '../plans/plans.repository';
import type { Logger } from '../shared/logger/logger';
import type { SubscriptionsRepository } from '../subscriptions/subscriptions.repository';
@@ -233,6 +235,8 @@ export async function inviteMemberToOrganization({
organizationsRepository,
subscriptionsRepository,
plansRepository,
+ planEntitlementsRepository,
+ planEntitlementDefinitionRegistry,
inviterId,
expirationDelayDays,
maxInvitationsPerDay,
@@ -247,6 +251,8 @@ export async function inviteMemberToOrganization({
organizationsRepository: OrganizationsRepository;
subscriptionsRepository: SubscriptionsRepository;
plansRepository: PlansRepository;
+ planEntitlementsRepository: PlanEntitlementsRepository;
+ planEntitlementDefinitionRegistry: PlanEntitlementDefinitionRegistry;
inviterId: string;
expirationDelayDays: number;
maxInvitationsPerDay: number;
@@ -313,6 +319,8 @@ export async function inviteMemberToOrganization({
organizationId,
subscriptionsRepository,
plansRepository,
+ planEntitlementsRepository,
+ planEntitlementDefinitionRegistry,
});
if (
@@ -526,15 +534,25 @@ export async function getOrganizationStorageLimits({
organizationId,
plansRepository,
subscriptionsRepository,
+ planEntitlementsRepository,
+ planEntitlementDefinitionRegistry,
documentsRepository,
}: {
organizationId: string;
plansRepository: PlansRepository;
subscriptionsRepository: SubscriptionsRepository;
+ planEntitlementsRepository: PlanEntitlementsRepository;
+ planEntitlementDefinitionRegistry: PlanEntitlementDefinitionRegistry;
documentsRepository: DocumentsRepository;
}) {
const [{ organizationPlan }, { totalDocumentsSize }] = await Promise.all([
- getOrganizationPlan({ organizationId, subscriptionsRepository, plansRepository }),
+ getOrganizationPlan({
+ organizationId,
+ subscriptionsRepository,
+ plansRepository,
+ planEntitlementsRepository,
+ planEntitlementDefinitionRegistry,
+ }),
documentsRepository.getOrganizationStats({ organizationId }),
]);
diff --git a/apps/papra-server/src/modules/plan-entitlements/plan-entitlements.config.ts b/apps/papra-server/src/modules/plan-entitlements/plan-entitlements.config.ts
new file mode 100644
index 00000000..135e51d1
--- /dev/null
+++ b/apps/papra-server/src/modules/plan-entitlements/plan-entitlements.config.ts
@@ -0,0 +1,6 @@
+import type { AppConfigDefinition } from '../config/config.types';
+import { selfhstEntitlementsConfig } from './selfhst/selfhst.plan-entitlements.config';
+
+export const planEntitlementsConfig = {
+ selfhst: selfhstEntitlementsConfig,
+} as const satisfies AppConfigDefinition;
diff --git a/apps/papra-server/src/modules/plan-entitlements/plan-entitlements.constants.ts b/apps/papra-server/src/modules/plan-entitlements/plan-entitlements.constants.ts
new file mode 100644
index 00000000..cda29219
--- /dev/null
+++ b/apps/papra-server/src/modules/plan-entitlements/plan-entitlements.constants.ts
@@ -0,0 +1,12 @@
+import { createPrefixedIdRegex } from '../shared/random/ids.constants.models';
+
+export const planEntitlementIdPrefix = 'pla_ent';
+export const planEntitlementIdRegex = createPrefixedIdRegex({ prefix: planEntitlementIdPrefix });
+
+export const PLAN_ENTITLEMENT_SOURCES = {
+ ADMIN: 'admin',
+ USER_CLAIM: 'user-claim',
+} as const;
+
+export type PlanEntitlementSource =
+ (typeof PLAN_ENTITLEMENT_SOURCES)[keyof typeof PLAN_ENTITLEMENT_SOURCES];
diff --git a/apps/papra-server/src/modules/plan-entitlements/plan-entitlements.registry.ts b/apps/papra-server/src/modules/plan-entitlements/plan-entitlements.registry.ts
new file mode 100644
index 00000000..bf39c76d
--- /dev/null
+++ b/apps/papra-server/src/modules/plan-entitlements/plan-entitlements.registry.ts
@@ -0,0 +1,49 @@
+import { injectArguments } from '@corentinth/chisels';
+import type {
+ PlanEntitlementDriver,
+ PlanEntitlementDriverFactoryParams,
+} from './plan-entitlements.types';
+import { selfhstPlanEntitlementsFactory } from './selfhst/selfhst.plan-entitlements';
+import { SELFHST_ENTITLEMENT_NAME } from './selfhst/selfhst.plan-entitlements.constants';
+
+export const planEntitlementsDefinitionFactories = {
+ [SELFHST_ENTITLEMENT_NAME]: selfhstPlanEntitlementsFactory,
+};
+
+export type PlanEntitlementType = keyof typeof planEntitlementsDefinitionFactories;
+
+export type PlanEntitlementDefinitionRegistry = ReturnType<
+ typeof createPlanEntitlementDefinitionRegistry
+>;
+
+type PlanEntitlementDefinitionRegistryLookup = Record<PlanEntitlementType, PlanEntitlementDriver>;
+
+export function createPlanEntitlementDefinitionRegistry(
+ params: PlanEntitlementDriverFactoryParams,
+) {
+ const registry: PlanEntitlementDefinitionRegistryLookup = Object.entries(
+ planEntitlementsDefinitionFactories,
+ ).reduce(
+ (registry, [type, factory]) => ({
+ ...registry,
+ [type]: factory(params),
+ }),
+ {} as PlanEntitlementDefinitionRegistryLookup,
+ );
+
+ return injectArguments({ getPlanEntitlementDriver }, { registry });
+}
+
+function getPlanEntitlementDriver({
+ type,
+ registry,
+}: {
+ type: PlanEntitlementType;
+ registry: PlanEntitlementDefinitionRegistryLookup;
+}): { planEntitlementDriver: PlanEntitlementDriver | undefined } {
+ const planEntitlementDriver = registry[type];
+
+ return {
+ planEntitlementDriver,
+ };
+}
diff --git a/apps/papra-server/src/modules/plan-entitlements/plan-entitlements.repository.ts b/apps/papra-server/src/modules/plan-entitlements/plan-entitlements.repository.ts
new file mode 100644
index 00000000..6c889c0d
--- /dev/null
+++ b/apps/papra-server/src/modules/plan-entitlements/plan-entitlements.repository.ts
@@ -0,0 +1,81 @@
+import { injectArguments } from '@corentinth/chisels';
+import type { Database } from '../app/database/database.types';
+import { planEntitlementsTable } from './plan-entitlements.tables';
+import { and, eq, getTableColumns, gt, isNull, or } from 'drizzle-orm';
+import { systemClock } from '../shared/clock/clock';
+import type { Clock } from '../shared/clock/clock.types';
+import { organizationMembersTable } from '../organizations/organizations.table';
+import { ORGANIZATION_ROLES } from '../organizations/organizations.constants';
+import type { Logger } from '@crowlog/logger';
+import { createLogger } from '../shared/logger/logger';
+
+export type PlanEntitlementsRepository = ReturnType<typeof createPlanEntitlementsRepository>;
+
+export function createPlanEntitlementsRepository({
+ db,
+ clock,
+ logger,
+}: {
+ db: Database;
+ clock?: Clock;
+ logger?: Logger;
+}) {
+ return injectArguments({ getActiveEntitlementForOrganization }, { db, clock, logger });
+}
+
+async function getActiveEntitlementForOrganization({
+ db,
+ organizationId,
+ clock = systemClock,
+ logger = createLogger({ namespace: 'planEntitlementsRepository' }),
+}: {
+ db: Database;
+ organizationId: string;
+ clock?: Clock;
+ logger?: Logger;
+}) {
+ const now = clock.now().epochMilliseconds;
+
+ const entitlements = await db
+ .select({ planEntitlements: getTableColumns(planEntitlementsTable) })
+ .from(planEntitlementsTable)
+ .innerJoin(
+ organizationMembersTable,
+ eq(planEntitlementsTable.userId, organizationMembersTable.userId),
+ )
+ .where(
+ and(
+ eq(organizationMembersTable.organizationId, organizationId),
+ eq(organizationMembersTable.role, ORGANIZATION_ROLES.OWNER),
+ or(
+ isNull(planEntitlementsTable.expiresAt),
+ gt(planEntitlementsTable.expiresAt, new Date(now)),
+ ),
+ ),
+ );
+
+ if (entitlements.length > 1) {
+ logger.warn(
+ {
+ organizationId,
+ ownerUserIds: entitlements.map((e) => e.planEntitlements.userId),
+ entitlementIds: entitlements.map((e) => e.planEntitlements.id),
+ },
+ 'Multiple active entitlements found for organization, returning the most recent one based on grantedAt',
+ );
+ }
+
+ const mostRecentEntitlement = entitlements.reduce((mostRecent, current) => {
+ if (!mostRecent) {
+ return current;
+ }
+
+ return current.planEntitlements.grantedAt > mostRecent.planEntitlements.grantedAt
+ ? current
+ : mostRecent;
+ }, entitlements[0]);
+
+ return {
+ planEntitlement: mostRecentEntitlement?.planEntitlements,
+ };
+}
diff --git a/apps/papra-server/src/modules/plan-entitlements/plan-entitlements.tables.ts b/apps/papra-server/src/modules/plan-entitlements/plan-entitlements.tables.ts
new file mode 100644
index 00000000..afc2d9e7
--- /dev/null
+++ b/apps/papra-server/src/modules/plan-entitlements/plan-entitlements.tables.ts
@@ -0,0 +1,30 @@
+import { integer, sqliteTable, text, unique } from 'drizzle-orm/sqlite-core';
+import { createPrimaryKeyField, createTimestampColumns } from '../shared/db/columns.helpers';
+import type { PlanEntitlementSource } from './plan-entitlements.constants';
+import { planEntitlementIdPrefix } from './plan-entitlements.constants';
+import { usersTable } from '../users/users.table';
+import type { PlanEntitlementType } from './plan-entitlements.registry';
+
+export const planEntitlementsTable = sqliteTable(
+ 'user_plan_entitlements',
+ {
+ ...createPrimaryKeyField({ prefix: planEntitlementIdPrefix }),
+ ...createTimestampColumns(),
+
+ grantedAt: integer('granted_at', { mode: 'timestamp_ms' }).notNull(),
+ expiresAt: integer('expires_at', { mode: 'timestamp_ms' }),
+ lastVerifiedAt: integer('last_verified_at', { mode: 'timestamp_ms' }),
+ userId: text('user_id')
+ .references(() => usersTable.id, {
+ onDelete: 'cascade',
+ onUpdate: 'cascade',
+ })
+ .notNull(),
+ type: text('type').notNull().$type<PlanEntitlementType>(),
+ source: text('source').notNull().$type<PlanEntitlementSource>(),
+ },
+ (table) => [
+ // To ensure entitlements are unique per user
+ unique('user_plan_entitlements_user_id_type_unique').on(table.userId, table.type),
+ ],
+);
diff --git a/apps/papra-server/src/modules/plan-entitlements/plan-entitlements.types.ts b/apps/papra-server/src/modules/plan-entitlements/plan-entitlements.types.ts
new file mode 100644
index 00000000..97c61c65
--- /dev/null
+++ b/apps/papra-server/src/modules/plan-entitlements/plan-entitlements.types.ts
@@ -0,0 +1,16 @@
+import type { Config } from '../config/config.types';
+import type { PlanId } from '../plans/plans.constants';
+
+export type PlanEntitlementDriver = {
+ verifyEligibility: (params: { userId: string }) => Promise<boolean>;
+ getIsEnabledForNewClaims: () => Promise<boolean>;
+ planId: PlanId;
+};
+
+export type PlanEntitlementDriverFactoryParams = {
+ config: Config;
+};
+
+export type PlanEntitlementDriverFactory = (
+ params: PlanEntitlementDriverFactoryParams,
+) => PlanEntitlementDriver;
diff --git a/apps/papra-server/src/modules/plan-entitlements/plan-entitlements.usecases.ts b/apps/papra-server/src/modules/plan-entitlements/plan-entitlements.usecases.ts
new file mode 100644
index 00000000..ad382d7c
--- /dev/null
+++ b/apps/papra-server/src/modules/plan-entitlements/plan-entitlements.usecases.ts
@@ -0,0 +1,42 @@
+import type { Logger } from '@crowlog/logger';
+import type { PlanId } from '../plans/plans.constants';
+import { isNil } from '../shared/utils';
+import type { PlanEntitlementDefinitionRegistry } from './plan-entitlements.registry';
+import type { PlanEntitlementsRepository } from './plan-entitlements.repository';
+import { createLogger } from '../shared/logger/logger';
+
+export async function resolveOrganizationPlanEntitlements({
+ organizationId,
+ planEntitlementsRepository,
+ planEntitlementDefinitionRegistry,
+ logger = createLogger({ namespace: 'resolveOrganizationPlanEntitlements' }),
+}: {
+ organizationId: string;
+ planEntitlementsRepository: PlanEntitlementsRepository;
+ planEntitlementDefinitionRegistry: PlanEntitlementDefinitionRegistry;
+ logger?: Logger;
+}): Promise<{ planId: PlanId | undefined }> {
+ const { planEntitlement } = await planEntitlementsRepository.getActiveEntitlementForOrganization({
+ organizationId,
+ });
+
+ if (!planEntitlement) {
+ return { planId: undefined };
+ }
+
+ const { type } = planEntitlement;
+
+ const { planEntitlementDriver } = planEntitlementDefinitionRegistry.getPlanEntitlementDriver({
+ type,
+ });
+
+ if (isNil(planEntitlementDriver)) {
+ logger.error({ type }, 'No plan entitlement driver found for type');
+
+ return { planId: undefined };
+ }
+
+ const { planId } = planEntitlementDriver;
+
+ return { planId };
+}
diff --git a/apps/papra-server/src/modules/plan-entitlements/selfhst/selfhst.plan-entitlements.config.ts b/apps/papra-server/src/modules/plan-entitlements/selfhst/selfhst.plan-entitlements.config.ts
new file mode 100644
index 00000000..f0ce3048
--- /dev/null
+++ b/apps/papra-server/src/modules/plan-entitlements/selfhst/selfhst.plan-entitlements.config.ts
@@ -0,0 +1,11 @@
+import { booleanishSchema } from '../../config/config.schemas';
+import type { AppConfigDefinition } from '../../config/config.types';
+
+export const selfhstEntitlementsConfig = {
+ isEnabledForNewClaims: {
+ doc: 'Whether the selfhst free plan entitlements is enabled for new claims.',
+ schema: booleanishSchema,
+ default: true,
+ env: 'SELFHST_ENTITLEMENTS_IS_ENABLED_FOR_NEW_CLAIMS',
+ },
+} as const satisfies AppConfigDefinition;
diff --git a/apps/papra-server/src/modules/plan-entitlements/selfhst/selfhst.plan-entitlements.constants.ts b/apps/papra-server/src/modules/plan-entitlements/selfhst/selfhst.plan-entitlements.constants.ts
new file mode 100644
index 00000000..15f3be50
--- /dev/null
+++ b/apps/papra-server/src/modules/plan-entitlements/selfhst/selfhst.plan-entitlements.constants.ts
@@ -0,0 +1 @@
+export const SELFHST_ENTITLEMENT_NAME = 'selfhst-premium';
diff --git a/apps/papra-server/src/modules/plan-entitlements/selfhst/selfhst.plan-entitlements.ts b/apps/papra-server/src/modules/plan-entitlements/selfhst/selfhst.plan-entitlements.ts
new file mode 100644
index 00000000..b1cd5b5d
--- /dev/null
+++ b/apps/papra-server/src/modules/plan-entitlements/selfhst/selfhst.plan-entitlements.ts
@@ -0,0 +1,12 @@
+import { PLAN_IDS } from '../../plans/plans.constants';
+import type { PlanEntitlementDriverFactory } from '../plan-entitlements.types';
+
+export const selfhstPlanEntitlementsFactory: PlanEntitlementDriverFactory = ({ config }) => {
+ const selfhstConfig = config.planEntitlements.selfhst;
+
+ return {
+ getIsEnabledForNewClaims: async () => selfhstConfig.isEnabledForNewClaims,
+ verifyEligibility: async () => false, // Temporary, waiting for implementation
+ planId: PLAN_IDS.FREE_EXTENDED,
+ };
+};
diff --git a/apps/papra-server/src/modules/plans/plans.constants.ts b/apps/papra-server/src/modules/plans/plans.constants.ts
index 13b8982d..26298896 100644
--- a/apps/papra-server/src/modules/plans/plans.constants.ts
+++ b/apps/papra-server/src/modules/plans/plans.constants.ts
@@ -1,5 +1,17 @@
export const PLAN_IDS = {
FREE: 'free',
+ FREE_EXTENDED: 'free-extended', // For partnerships
PLUS: 'plus',
PRO: 'pro',
} as const;
+
+export const FREE_PLANS_IDS = [PLAN_IDS.FREE, PLAN_IDS.FREE_EXTENDED] as const;
+
+export const PLAN_PRIORITY: Record<PlanId, number> = {
+ [PLAN_IDS.FREE]: 0,
+ [PLAN_IDS.FREE_EXTENDED]: 1,
+ [PLAN_IDS.PLUS]: 2,
+ [PLAN_IDS.PRO]: 3,
+};
+
+export type PlanId = (typeof PLAN_IDS)[keyof typeof PLAN_IDS];
diff --git a/apps/papra-server/src/modules/plans/plans.models.ts b/apps/papra-server/src/modules/plans/plans.models.ts
index 90b73462..3bd690df 100644
--- a/apps/papra-server/src/modules/plans/plans.models.ts
+++ b/apps/papra-server/src/modules/plans/plans.models.ts
@@ -1,4 +1,5 @@
import { isNil } from '../shared/utils';
+import { PLAN_PRIORITY, type PlanId } from './plans.constants';
import { createOrganizationPlanPriceIdNotSetError } from './plans.errors';
export function getPriceIdForBillingInterval({
@@ -18,3 +19,24 @@ export function getPriceIdForBillingInterval({
return { priceId };
}
+
+export function getApplyablePlanId({
+ basePlanId,
+ entitlementPlanId,
+}: {
+ basePlanId: PlanId;
+ entitlementPlanId?: PlanId;
+}) {
+ if (isNil(entitlementPlanId)) {
+ return { applyablePlanId: basePlanId };
+ }
+
+ const basePlanPriority = PLAN_PRIORITY[basePlanId];
+ const entitlementPlanPriority = PLAN_PRIORITY[entitlementPlanId];
+
+ if (entitlementPlanPriority > basePlanPriority) {
+ return { applyablePlanId: entitlementPlanId };
+ }
+
+ return { applyablePlanId: basePlanId };
+}
diff --git a/apps/papra-server/src/modules/plans/plans.repository.ts b/apps/papra-server/src/modules/plans/plans.repository.ts
index ebc23aeb..4ea9c864 100644
--- a/apps/papra-server/src/modules/plans/plans.repository.ts
+++ b/apps/papra-server/src/modules/plans/plans.repository.ts
@@ -26,19 +26,31 @@ export function getOrganizationPlansRecords({ config }: { config: Config }) {
const { isFreePlanUnlimited } = config.organizationPlans;
const { maxUploadSize } = config.documentsStorage;
+ const freePlanLimits = {
+ maxDocumentStorageBytes: isFreePlanUnlimited
+ ? Number.POSITIVE_INFINITY
+ : 500 * IN_BYTES.MEGABYTE,
+ maxIntakeEmailsCount: isFreePlanUnlimited ? Number.POSITIVE_INFINITY : 1,
+ maxOrganizationsMembersCount: isFreePlanUnlimited ? Number.POSITIVE_INFINITY : 3,
+ maxFileSize: isDocumentSizeLimitEnabled({ maxUploadSize })
+ ? maxUploadSize
+ : Number.POSITIVE_INFINITY,
+ };
+
const organizationPlans: Record<string, OrganizationPlanRecord> = {
[PLAN_IDS.FREE]: {
id: PLAN_IDS.FREE,
name: 'Free',
+ limits: freePlanLimits,
+ },
+ [PLAN_IDS.FREE_EXTENDED]: {
+ id: PLAN_IDS.FREE_EXTENDED,
+ name: 'Free Extended',
limits: {
- maxDocumentStorageBytes: isFreePlanUnlimited
- ? Number.POSITIVE_INFINITY
- : 500 * IN_BYTES.MEGABYTE,
- maxIntakeEmailsCount: isFreePlanUnlimited ? Number.POSITIVE_INFINITY : 1,
- maxOrganizationsMembersCount: isFreePlanUnlimited ? Number.POSITIVE_INFINITY : 3,
- maxFileSize: isDocumentSizeLimitEnabled({ maxUploadSize })
- ? maxUploadSize
- : Number.POSITIVE_INFINITY,
+ maxDocumentStorageBytes: freePlanLimits.maxDocumentStorageBytes * 2,
+ maxIntakeEmailsCount: freePlanLimits.maxIntakeEmailsCount * 2,
+ maxOrganizationsMembersCount: freePlanLimits.maxOrganizationsMembersCount * 2,
+ maxFileSize: freePlanLimits.maxFileSize, // Same file size limit as Free plan
},
},
[PLAN_IDS.PLUS]: {
diff --git a/apps/papra-server/src/modules/plans/plans.usecases.test.ts b/apps/papra-server/src/modules/plans/plans.usecases.test.ts
index be387b60..c2b5416a 100644
--- a/apps/papra-server/src/modules/plans/plans.usecases.test.ts
+++ b/apps/papra-server/src/modules/plans/plans.usecases.test.ts
@@ -6,6 +6,8 @@ import { createSubscriptionsRepository } from '../subscriptions/subscriptions.re
import { PLAN_IDS } from './plans.constants';
import { createPlansRepository } from './plans.repository';
import { getOrganizationPlan } from './plans.usecases';
+import { createPlanEntitlementDefinitionRegistry } from '../plan-entitlements/plan-entitlements.registry';
+import { createPlanEntitlementsRepository } from '../plan-entitlements/plan-entitlements.repository';
describe('plans usecases', () => {
describe('getOrganizationPlan', () => {
@@ -40,11 +42,15 @@ describe('plans usecases', () => {
const plansRepository = createPlansRepository({ config });
const subscriptionsRepository = createSubscriptionsRepository({ db });
+ const planEntitlementsRepository = createPlanEntitlementsRepository({ db });
+ const planEntitlementDefinitionRegistry = createPlanEntitlementDefinitionRegistry({ config });
const { organizationPlan } = await getOrganizationPlan({
organizationId: 'organization-1',
subscriptionsRepository,
plansRepository,
+ planEntitlementsRepository,
+ planEntitlementDefinitionRegistry,
});
expect(organizationPlan.id).to.equal(PLAN_IDS.PLUS);
@@ -68,14 +74,108 @@ describe('plans usecases', () => {
const plansRepository = createPlansRepository({ config });
const subscriptionsRepository = createSubscriptionsRepository({ db });
+ const planEntitlementsRepository = createPlanEntitlementsRepository({ db });
+ const planEntitlementDefinitionRegistry = createPlanEntitlementDefinitionRegistry({ config });
const { organizationPlan } = await getOrganizationPlan({
organizationId: 'organization-1',
subscriptionsRepository,
plansRepository,
+ planEntitlementsRepository,
+ planEntitlementDefinitionRegistry,
});
expect(organizationPlan.id).to.equal(PLAN_IDS.FREE);
});
+
+ describe('plan entitlements', () => {
+ test('an organization owner may have a plan entitlement that overrides the organization subscription plan', async () => {
+ const { db } = await createInMemoryDatabase({
+ users: [{ id: 'user-1', email: '[email protected]' }],
+ organizations: [{ id: 'organization-1', name: 'Organization 1' }],
+ organizationMembers: [
+ { organizationId: 'organization-1', userId: 'user-1', role: ORGANIZATION_ROLES.OWNER },
+ ],
+ planEntitlements: [
+ {
+ id: 'entitlement-1',
+ userId: 'user-1',
+ type: 'selfhst-premium',
+ grantedAt: new Date('2026-01-01'),
+ source: 'user-claim',
+ },
+ ],
+ });
+
+ const config = overrideConfig();
+
+ const plansRepository = createPlansRepository({ config });
+ const subscriptionsRepository = createSubscriptionsRepository({ db });
+ const planEntitlementsRepository = createPlanEntitlementsRepository({ db });
+ const planEntitlementDefinitionRegistry = createPlanEntitlementDefinitionRegistry({
+ config,
+ });
+
+ const { organizationPlan } = await getOrganizationPlan({
+ organizationId: 'organization-1',
+ subscriptionsRepository,
+ plansRepository,
+ planEntitlementsRepository,
+ planEntitlementDefinitionRegistry,
+ });
+
+ expect(organizationPlan.id).to.equal(PLAN_IDS.FREE_EXTENDED);
+ });
+
+ test('if an organization have a better subscription plan than the plan entitlement, the subscription plan should be applied', async () => {
+ const { db } = await createInMemoryDatabase({
+ users: [{ id: 'user-1', email: '[email protected]' }],
+ organizations: [{ id: 'organization-1', name: 'Organization 1' }],
+ organizationMembers: [
+ { organizationId: 'organization-1', userId: 'user-1', role: ORGANIZATION_ROLES.OWNER },
+ ],
+ organizationSubscriptions: [
+ {
+ id: 'subscription-1',
+ organizationId: 'organization-1',
+ planId: PLAN_IDS.PLUS,
+ status: 'active',
+ currentPeriodEnd: new Date('2026-12-31'),
+ currentPeriodStart: new Date('2026-01-01'),
+ customerId: 'cus_123',
+ seatsCount: 10,
+ },
+ ],
+ planEntitlements: [
+ {
+ id: 'entitlement-1',
+ userId: 'user-1',
+ type: 'selfhst-premium',
+ grantedAt: new Date('2026-01-01'),
+ source: 'user-claim',
+ },
+ ],
+ });
+
+ const config = overrideConfig();
+
+ const plansRepository = createPlansRepository({ config });
+ const subscriptionsRepository = createSubscriptionsRepository({ db });
+ const planEntitlementsRepository = createPlanEntitlementsRepository({ db });
+ const planEntitlementDefinitionRegistry = createPlanEntitlementDefinitionRegistry({
+ config,
+ });
+
+ const { organizationPlan } = await getOrganizationPlan({
+ organizationId: 'organization-1',
+ subscriptionsRepository,
+ plansRepository,
+ planEntitlementsRepository,
+ planEntitlementDefinitionRegistry,
+ });
+
+ expect(organizationPlan.id).to.equal(PLAN_IDS.PLUS);
+ });
+ });
});
});
diff --git a/apps/papra-server/src/modules/plans/plans.usecases.ts b/apps/papra-server/src/modules/plans/plans.usecases.ts
index eb023eda..b1d5d660 100644
--- a/apps/papra-server/src/modules/plans/plans.usecases.ts
+++ b/apps/papra-server/src/modules/plans/plans.usecases.ts
@@ -1,23 +1,46 @@
import type { SubscriptionsRepository } from '../subscriptions/subscriptions.repository';
import type { PlansRepository } from './plans.repository';
+import type { PlanId } from './plans.constants';
import { PLAN_IDS } from './plans.constants';
+import { resolveOrganizationPlanEntitlements } from '../plan-entitlements/plan-entitlements.usecases';
+import { getApplyablePlanId } from './plans.models';
+import type { PlanEntitlementsRepository } from '../plan-entitlements/plan-entitlements.repository';
+import type { PlanEntitlementDefinitionRegistry } from '../plan-entitlements/plan-entitlements.registry';
export async function getOrganizationPlan({
organizationId,
subscriptionsRepository,
plansRepository,
+ planEntitlementsRepository,
+ planEntitlementDefinitionRegistry,
}: {
organizationId: string;
subscriptionsRepository: SubscriptionsRepository;
plansRepository: PlansRepository;
+ planEntitlementsRepository: PlanEntitlementsRepository;
+ planEntitlementDefinitionRegistry: PlanEntitlementDefinitionRegistry;
}) {
- const { subscription } = await subscriptionsRepository.getActiveOrganizationSubscription({
- organizationId,
- });
+ const [{ subscription }, { planId: entitlementPlanId }] = await Promise.all([
+ subscriptionsRepository.getActiveOrganizationSubscription({
+ organizationId,
+ }),
+ resolveOrganizationPlanEntitlements({
+ organizationId,
+ planEntitlementsRepository,
+ planEntitlementDefinitionRegistry,
+ }),
+ ]);
+
+ const basePlanId = (subscription?.planId ?? PLAN_IDS.FREE) as PlanId;
- const planId = subscription?.planId ?? PLAN_IDS.FREE;
+ const { applyablePlanId } = getApplyablePlanId({
+ basePlanId,
+ entitlementPlanId,
+ });
- const { organizationPlan } = await plansRepository.getOrganizationPlanById({ planId });
+ const { organizationPlan } = await plansRepository.getOrganizationPlanById({
+ planId: applyablePlanId,
+ });
return { organizationPlan };
}
diff --git a/apps/papra-server/src/modules/subscriptions/subscriptions.routes.ts b/apps/papra-server/src/modules/subscriptions/subscriptions.routes.ts
index 98de98ec..ae560d5b 100644
--- a/apps/papra-server/src/modules/subscriptions/subscriptions.routes.ts
+++ b/apps/papra-server/src/modules/subscriptions/subscriptions.routes.ts
@@ -12,8 +12,9 @@ import {
ensureUserIsOwnerOfOrganization,
getOrCreateOrganizationCustomerId,
} from '../organizations/organizations.usecases';
-import { PLAN_IDS } from '../plans/plans.constants';
+import { FREE_PLANS_IDS, PLAN_IDS } from '../plans/plans.constants';
import { getPriceIdForBillingInterval } from '../plans/plans.models';
+import { createPlanEntitlementsRepository } from '../plan-entitlements/plan-entitlements.repository';
import { createPlansRepository } from '../plans/plans.repository';
import { getOrganizationPlan } from '../plans/plans.usecases';
import { getHeader } from '../shared/headers/headers.models';
@@ -82,6 +83,7 @@ function setupCreateCheckoutSessionRoute({
config,
db,
subscriptionsServices,
+ planEntitlementDefinitionRegistry,
}: RouteDefinitionContext) {
app.post(
'/api/organizations/:organizationId/checkout-session',
@@ -103,6 +105,7 @@ function setupCreateCheckoutSessionRoute({
const organizationsRepository = createOrganizationsRepository({ db });
const plansRepository = createPlansRepository({ config });
const subscriptionsRepository = createSubscriptionsRepository({ db });
+ const planEntitlementsRepository = createPlanEntitlementsRepository({ db });
const { planId, billingInterval } = context.req.valid('json');
const { organizationId } = context.req.valid('param');
@@ -125,9 +128,11 @@ function setupCreateCheckoutSessionRoute({
organizationId,
subscriptionsRepository,
plansRepository,
+ planEntitlementsRepository,
+ planEntitlementDefinitionRegistry,
});
- if (organizationCurrentPlan.id !== PLAN_IDS.FREE) {
+ if (!FREE_PLANS_IDS.includes(organizationCurrentPlan.id)) {
throw createOrganizationAlreadyHasSubscriptionError();
}
@@ -266,7 +271,12 @@ function setupGetOrganizationSubscriptionRoute({ app, db, config }: RouteDefinit
);
}
-function setupGetOrganizationSubscriptionUsageRoute({ app, db, config }: RouteDefinitionContext) {
+function setupGetOrganizationSubscriptionUsageRoute({
+ app,
+ db,
+ config,
+ planEntitlementDefinitionRegistry,
+}: RouteDefinitionContext) {
app.get(
'/api/organizations/:organizationId/usage',
requireAuthentication(),
@@ -283,6 +293,7 @@ function setupGetOrganizationSubscriptionUsageRoute({ app, db, config }: RouteDe
const documentsRepository = createDocumentsRepository({ db });
const plansRepository = createPlansRepository({ config });
const intakeEmailsRepository = createIntakeEmailsRepository({ db });
+ const planEntitlementsRepository = createPlanEntitlementsRepository({ db });
await ensureUserIsInOrganization({
userId,
@@ -296,7 +307,13 @@ function setupGetOrganizationSubscriptionUsageRoute({ app, db, config }: RouteDe
{ intakeEmailCount },
{ membersCount },
] = await Promise.all([
- getOrganizationPlan({ organizationId, subscriptionsRepository, plansRepository }),
+ getOrganizationPlan({
+ organizationId,
+ subscriptionsRepository,
+ plansRepository,
+ planEntitlementsRepository,
+ planEntitlementDefinitionRegistry,
+ }),
documentsRepository.getOrganizationStats({ organizationId }),
intakeEmailsRepository.getOrganizationIntakeEmailsCount({ organizationId }),
organizationsRepository.getOrganizationMembersCount({ organizationId }),
diff --git a/apps/papra-server/src/start.ts b/apps/papra-server/src/start.ts
index 20dd5754..7c091de7 100644
--- a/apps/papra-server/src/start.ts
+++ b/apps/papra-server/src/start.ts
@@ -24,6 +24,7 @@ import { createTaskServices } from './modules/tasks/tasks.services';
import { createTrackingServices } from './modules/tracking/tracking.services';
import { createWebhookRepository } from './modules/webhooks/webhooks.repository';
import { createWebhookTriggerServices } from './modules/webhooks/webhooks.trigger.services';
+import { createPlanEntitlementDefinitionRegistry } from './modules/plan-entitlements/plan-entitlements.registry';
async function startWebMode({ logger, ...dependencies }: { logger: Logger } & GlobalDependencies) {
const server = createServer(dependencies);
@@ -71,6 +72,7 @@ async function buildServices({ config }: { config: Config }): Promise<GlobalDepe
webhookRepository,
});
const kvStore = buildKvStore({ config, db });
+ const planEntitlementDefinitionRegistry = createPlanEntitlementDefinitionRegistry({ config });
// --- Services initialization
await taskServices.initialize();
@@ -97,6 +99,7 @@ async function buildServices({ config }: { config: Config }): Promise<GlobalDepe
documentSearchServices,
webhookTriggerServices,
kvStore,
+ planEntitlementDefinitionRegistry,
};
}