@taskforcehq/taskforce 0.3.301 → 0.3.303

package/dist/core/Taskforce.d.ts

@@ -86,6 +86,7 @@ export interface TaskActor {
 export interface TaskItem {
     id: string;
     referenceNumber?: number | null;
+    localReferenceNumber?: number | null;
     referenceLabel?: string;
     title: string;
     description: string | null;
@@ -342,14 +343,10 @@ export interface InitiativeTemplate {
     milestones: InitiativeTemplateMilestone[];
 }
 type WorkspaceSyncSettingsPayload = Record<string, Record<string, unknown>>;
-type SignupMonetizationStrategy = 'auto_assign_default' | 'plan_selection_required';
-interface SignupMonetizationSettings {
-    strategy: SignupMonetizationStrategy;
-    defaultSignupPlanVersionId: string | null;
-}
 type AccessRole = 'owner' | 'admin' | 'member' | 'read-only';
 export type SystemRole = 'system_admin' | 'user';
 type PermissionMode = 'read-only' | 'read-write';
+type AuthTokenPurpose = 'email_verification' | 'password_reset' | 'invite_accept';
 export type McpAccessTokenScope = 'tasks:read' | 'tasks:write' | 'workspace:read';
 type McpAccessTokenStatus = 'active' | 'revoked' | 'expired';
 export type McpOAuthProvider = 'chatgpt' | 'claude';
@@ -367,9 +364,24 @@ interface UserIdentityRecord {
     userId: string;
     email: string;
     displayName?: string | null;
+    avatarUrl?: string | null;
     systemRole?: SystemRole;
     betaAccess?: boolean;
 }
+interface UserAvatarUploadDraftRecord {
+    draftId: string;
+    userId: string;
+    storageKey: string;
+    mimeType: string;
+    originalFilename: string;
+    sizeBytes: number;
+    storageProvider: 'local' | 'r2' | 'external';
+    finalizedAt?: string | null;
+    consumedAt?: string | null;
+    discardedAt?: string | null;
+    createdAt: string;
+    updatedAt: string;
+}
 interface WorkspaceUserRecord {
     userId: string;
     email: string;
@@ -437,6 +449,24 @@ interface SystemUserRecord {
     updatedAt?: string | null;
     emailVerifiedAt?: string | null;
 }
+export interface PurgedSystemUserSummary {
+    targetUserId: string;
+    email: string;
+    unassignedTaskCount: number;
+    clearedInitiativeOwnerCount: number;
+    clearedWorkstreamOwnerCount: number;
+    deletedWorkspaceMembershipCount: number;
+    deletedAuthTokenCount: number;
+    deletedAvatarDraftCount: number;
+    deletedMcpAccessTokenCount: number;
+    deletedMcpOauthAuthCodeCount: number;
+    deletedMcpOauthConnectorGrantCount: number;
+    deletedUiStateCount: number;
+    deletedUserPreferenceCount: number;
+    deletedEntitlementCount: number;
+    deletedUserBillingCount: number;
+    deletedUserCount: number;
+}
 export type SetupState = 'present' | 'missing' | 'unreadable';
 export type RuntimeMode = 'local' | 'cloud';
 export type WorkspaceMode = 'core' | 'operations';
@@ -476,6 +506,8 @@ interface CreateTaskOptions {
     persistBackup?: boolean;
     workspaceId?: string;
     allowClientProvidedId?: boolean;
+    provisionalLocalReference?: boolean;
+    preferIncomingReferenceNumberOnConflict?: boolean;
     skipRecompute?: boolean;
     syncUpdatedAt?: string;
     actorRef?: string;
@@ -511,7 +543,7 @@ interface McpAuditLogRecord {
     reasonCode: string | null;
     details: Record<string, unknown>;
 }
-export type EntitlementState = 'active' | 'trialing' | 'grace' | 'suspended' | 'canceled';
+export type EntitlementState = 'pending_plan_selection' | 'checkout_pending' | 'active' | 'trialing' | 'grace' | 'suspended' | 'canceled';
 export type PlanFeatureAccess = 'enabled' | 'disabled' | 'limited';
 export interface PlanFeatureSnapshot {
     featureKey: string;
@@ -573,6 +605,11 @@ interface PasswordAuthResult {
     };
     code?: 'INVALID_CREDENTIALS' | 'EMAIL_NOT_VERIFIED';
 }
+interface AuthTokenInspection {
+    state: 'valid' | 'expired' | 'used' | 'missing' | 'revoked';
+    userId?: string;
+    workspaceId?: string;
+}
 export interface McpAccessTokenRecord {
     id: string;
     workspaceId: string;
@@ -849,8 +886,20 @@ export declare class TaskforceCore implements TaskforceSyncCapable {
     getWorkspaceAssetStore(): WorkspaceAssetStore;
     private normalizeEntitlementState;
     private upsertCanonicalEntitlementRecord;
+    transitionCanonicalCommercialState(input: {
+        accountId: string;
+        planVersionId?: string | null;
+        state: EntitlementState;
+        effectiveAt?: string | null;
+        effectiveUntil?: string | null;
+        billingMirrorPlanId?: string | null;
+        source: 'registration' | 'checkout-start' | 'checkout-confirm' | 'stripe-webhook' | 'backfill' | 'legacy-plan-mode' | 'admin' | 'system';
+        updatedBy: string;
+        createdAt?: string | null;
+        updatedAt?: string | null;
+    }): import("./types.js").AccountEntitlementSnapshot;
     private resolveWorkspaceLimitForUser;
-    private resolveRegistrationPlanAssignment;
+    private resolveRegistrationOnboardingOutcome;
     createUserBillingRecord(userId: string, options?: {
         entitlementState?: string;
         planId?: string | null;
@@ -940,8 +989,11 @@ export declare class TaskforceCore implements TaskforceSyncCapable {
     hasProjectThemeOverride(workspaceId?: string, userId?: string): boolean;
     getEffectiveTheme(workspaceId?: string, userId?: string): TaskforceTheme;
     hasProjectJsonBackupOverride(workspaceId?: string, userId?: string): boolean;
-    getSignupMonetizationSettings(): import("./types.js").SignupMonetizationSettings;
-    validateSignupMonetizationSettings(input?: Partial<SignupMonetizationSettings>): import("./types.js").SignupMonetizationValidationResult;
+    getOnboardingPolicy(): import("./types.js").OnboardingPolicy;
+    validateOnboardingPolicy(input?: {
+        mode?: 'require_plan_selection' | 'auto_grant_free' | 'auto_start_trial';
+        planVersionId?: string | null;
+    }): import("./types.js").OnboardingPolicyValidationResult;
     updateGlobalSettings(settings: GlobalTaskforceSettings): void;
     private sanitizeUserGlobalSyncSettings;
     getUserGlobalSyncSettings(userId: string): {
@@ -971,7 +1023,9 @@ export declare class TaskforceCore implements TaskforceSyncCapable {
     private rowToWorkstream;
     private rowToChecklistItem;
     private sanitizeTaskReferenceNumber;
+    private getTaskReferencePolicyDeps;
     private getTaskByReferenceNumber;
+    private getTaskByLocalReferenceNumber;
     resolveTaskIdentifier(value: string, workspaceId?: string): TaskItem | null;
     getInitiative(id: string, workspaceId?: string): InitiativeItem | null;
     listInitiatives(workspaceId?: string): InitiativeItem[];
@@ -989,6 +1043,15 @@ export declare class TaskforceCore implements TaskforceSyncCapable {
     upsertWorkstreamForSync(workstream: WorkstreamItem, workspaceId?: string | null): WorkstreamItem;
     listChecklistItems(taskId: string, workspaceId?: string): ChecklistItem[];
     replaceChecklistItems(taskId: string, items: Array<Partial<ChecklistItem>>, workspaceId?: string): ChecklistItem[];
+    private getTaskReferenceSequenceValue;
+    private getLocalTaskReferenceSequenceValue;
+    private getMaxTaskReferenceNumber;
+    private getMaxLocalTaskReferenceNumber;
+    private persistTaskReferenceSequence;
+    private persistLocalTaskReferenceSequence;
+    private allocateNextTaskReferenceNumber;
+    private allocateNextLocalTaskReferenceNumber;
+    private relocateTaskReferenceConflict;
     private reserveTaskReferenceNumber;
     private reserveGenericReferenceNumber;
     private reserveInitiativeReferenceNumber;
@@ -1081,7 +1144,25 @@ export declare class TaskforceCore implements TaskforceSyncCapable {
     }): UserAccessRecord;
     resolveUserAccess(userId: string, workspaceId: string, fallbackRole?: AccessRole): UserAccessRecord | null;
     resolveUserIdentity(userId: string): UserIdentityRecord | null;
+    updateUserProfile(userId: string, input: {
+        displayName: string;
+        avatarUrl?: string | null;
+    }): UserIdentityRecord | null;
     updateUserDisplayName(userId: string, displayName: string): UserIdentityRecord | null;
+    createUserAvatarUploadDraft(input: {
+        userId: string;
+        draftId: string;
+        storageKey: string;
+        mimeType: string;
+        originalFilename: string;
+        sizeBytes: number;
+        storageProvider?: 'local' | 'r2' | 'external';
+    }): UserAvatarUploadDraftRecord;
+    getUserAvatarUploadDraft(userId: string, draftId: string): UserAvatarUploadDraftRecord | null;
+    markUserAvatarUploadDraftFinalized(userId: string, draftId: string): UserAvatarUploadDraftRecord | null;
+    markUserAvatarUploadDraftConsumed(userId: string, draftId: string): UserAvatarUploadDraftRecord | null;
+    discardUserAvatarUploadDraft(userId: string, draftId: string): UserAvatarUploadDraftRecord | null;
+    cleanupStaleUserAvatarUploadDrafts(userId: string, olderThanIso: string): UserAvatarUploadDraftRecord[];
     getSystemRole(userId: string): SystemRole;
     getUserBetaAccess(userId: string): boolean;
     countSystemAdmins(): number;
@@ -1090,6 +1171,11 @@ export declare class TaskforceCore implements TaskforceSyncCapable {
     setSystemRole(userId: string, role: SystemRole): boolean;
     setUserDisabledGlobal(userId: string, disabled: boolean): boolean;
     setUserBetaAccessGlobal(userId: string, enabled: boolean): boolean;
+    purgeSystemUser(input: {
+        targetUserId: string;
+        actorUserId: string;
+        emailConfirmation: string;
+    }): PurgedSystemUserSummary;
     private clearActiveAssignmentsForUnavailableActor;
     listWorkspaceUsers(workspaceId: string): WorkspaceUserRecord[];
     replaceWorkspaceUsersForSync(input: {
@@ -1424,10 +1510,12 @@ export declare class TaskforceCore implements TaskforceSyncCapable {
         workspaceId: string | null;
         role: AccessRole;
         planSelectionRequired: boolean;
+        checkoutPending: boolean;
+        commercialState: EntitlementState;
     };
     private createOneTimeAuthToken;
     private consumeOneTimeAuthToken;
-    private inspectOneTimeAuthToken;
+    inspectOneTimeAuthToken(token: string, purpose: AuthTokenPurpose): AuthTokenInspection;
     revokeMcpCredentialsForUserWorkspace(userId: string, workspaceId: string, revokedByUserId?: string | null): void;
     private revokeMcpCredentialsForWorkspace;
     listMcpAccessTokens(input: {
@@ -1602,9 +1690,11 @@ export declare class TaskforceCore implements TaskforceSyncCapable {
         validateOnly?: boolean;
         workspaceId?: string;
         allowClientProvidedId?: boolean;
+        provisionalLocalReference?: boolean;
     }): BulkCreateTaskResult;
     updateTask(id: string, updates: Partial<TaskItem>, workspaceId?: string, options?: {
         persistBackup?: boolean;
+        preferIncomingReferenceNumberOnConflict?: boolean;
         skipRecompute?: boolean;
         syncUpdatedAt?: string;
         actorRef?: string;

package/dist/core/Taskforce.ids.test.js

@@ -80,6 +80,139 @@ describe('TaskforceCore id policy', () => {
             cleanup();
         }
     });
+    it('assigns provisional local task references without consuming canonical task references', () => {
+        const { core, cleanup } = makeCore();
+        try {
+            const provisionalFirst = core.createTask({ title: 'Offline first' }, {
+                workspaceId: 'workspace-a',
+                provisionalLocalReference: true
+            });
+            const provisionalSecond = core.createTask({ title: 'Offline second' }, {
+                workspaceId: 'workspace-a',
+                provisionalLocalReference: true
+            });
+            const canonical = core.createTask({ title: 'Cloud-backed task' }, { workspaceId: 'workspace-a' });
+            expect(provisionalFirst.referenceNumber).toBeNull();
+            expect(provisionalFirst.localReferenceNumber).toBe(1);
+            expect(provisionalFirst.referenceLabel).toBe('LT-1');
+            expect(provisionalSecond.referenceNumber).toBeNull();
+            expect(provisionalSecond.localReferenceNumber).toBe(2);
+            expect(provisionalSecond.referenceLabel).toBe('LT-2');
+            expect(canonical.referenceNumber).toBe(1);
+            expect(canonical.localReferenceNumber).toBeNull();
+            expect(canonical.referenceLabel).toBe('T-1');
+        }
+        finally {
+            cleanup();
+        }
+    });
+    it('replaces a provisional local reference with a canonical cloud reference during sync apply', () => {
+        const { core, cleanup } = makeCore();
+        try {
+            const provisional = core.createTask({ title: 'Offline draft' }, {
+                workspaceId: 'workspace-a',
+                provisionalLocalReference: true
+            });
+            expect(provisional.referenceLabel).toBe('LT-1');
+            const syncResult = core.applyWorkspaceSyncSnapshot({
+                tasks: [
+                    {
+                        id: provisional.id,
+                        title: 'Offline draft',
+                        status: 'task',
+                        referenceNumber: 7,
+                        updatedAt: '2099-04-10T17:00:00.000Z'
+                    }
+                ]
+            }, 'workspace-a');
+            expect(syncResult.updated).toBe(1);
+            expect(core.getTask(provisional.id, 'workspace-a')).toEqual(expect.objectContaining({
+                referenceNumber: 7,
+                localReferenceNumber: null,
+                referenceLabel: 'T-7'
+            }));
+        }
+        finally {
+            cleanup();
+        }
+    });
+    it('preserves provisional local references across core reloads', () => {
+        const projectRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'taskforce-id-reload-test-'));
+        const storagePath = path.join(projectRoot, '.taskforce');
+        const firstCore = new TaskforceCore({ projectRoot, storagePath });
+        try {
+            const provisional = firstCore.createTask({ title: 'Offline draft' }, {
+                workspaceId: 'workspace-a',
+                provisionalLocalReference: true
+            });
+            expect(provisional.referenceNumber).toBeNull();
+            expect(provisional.localReferenceNumber).toBe(1);
+            firstCore.close();
+            const reloadedCore = new TaskforceCore({ projectRoot, storagePath });
+            try {
+                const reloadedTask = reloadedCore.getTask(provisional.id, 'workspace-a');
+                expect(reloadedTask).toEqual(expect.objectContaining({
+                    referenceNumber: null,
+                    localReferenceNumber: 1,
+                    referenceLabel: 'LT-1'
+                }));
+            }
+            finally {
+                reloadedCore.close();
+            }
+        }
+        finally {
+            fs.rmSync(projectRoot, { recursive: true, force: true });
+        }
+    });
+    it('lets the incoming synced task keep its preferred reference and renumbers the local incumbent', () => {
+        const { core, cleanup } = makeCore();
+        try {
+            const localTask = core.createTask({ title: 'Local task' }, { workspaceId: 'workspace-a' });
+            const syncResult = core.applyWorkspaceSyncSnapshot({
+                tasks: [
+                    {
+                        id: 'task-sync-imported-collision',
+                        title: 'Remote task',
+                        status: 'task',
+                        referenceNumber: localTask.referenceNumber,
+                        createdAt: '2026-04-10T15:00:00.000Z',
+                        updatedAt: '2026-04-10T15:00:00.000Z',
+                    }
+                ]
+            }, 'workspace-a');
+            expect(syncResult.created).toBe(1);
+            expect(core.getTask(localTask.id, 'workspace-a')?.referenceLabel).toBe('T-2');
+            expect(core.getTask('task-sync-imported-collision', 'workspace-a')?.referenceLabel).toBe('T-1');
+        }
+        finally {
+            cleanup();
+        }
+    });
+    it('lets incoming synced updates claim the preferred reference and renumbers the displaced task', () => {
+        const { core, cleanup } = makeCore();
+        try {
+            const first = core.createTask({ title: 'First' }, { workspaceId: 'workspace-a' });
+            const second = core.createTask({ title: 'Second' }, { workspaceId: 'workspace-a' });
+            const syncResult = core.applyWorkspaceSyncSnapshot({
+                tasks: [
+                    {
+                        id: second.id,
+                        title: 'Second',
+                        status: 'task',
+                        referenceNumber: first.referenceNumber,
+                        updatedAt: '2099-04-11T16:00:00.000Z',
+                    }
+                ]
+            }, 'workspace-a');
+            expect(syncResult.updated).toBe(1);
+            expect(core.getTask(first.id, 'workspace-a')?.referenceLabel).toBe('T-3');
+            expect(core.getTask(second.id, 'workspace-a')?.referenceLabel).toBe('T-1');
+        }
+        finally {
+            cleanup();
+        }
+    });
     it('resolves task identifiers by task reference or internal id', () => {
         const { core, cleanup } = makeCore();
         try {