musora-content-services 2.176.0 → 2.177.0

package/.agent/decisions/2026-08-17-password-reset-mobile-token.md

@@ -0,0 +1,27 @@
+---
+date: 2026-08-17
+branch: fix/password-reset-mobile-token
+pr: https://github.com/railroadmedia/musora-content-services/pull/1031
+status: open
+tags: [bug-fix]
+---
+
+# Password reset mobile token and sessionConfig access
+
+## Context
+Mobile app needed `resetPassword` to return an authenticated session directly (avoiding a separate login step after reset), and two OAuth session functions were reading `userId` from a stale top-level `globalConfig.userId` field instead of the current `globalConfig.sessionConfig.userId` shape.
+
+## Decision
+- `resetPassword` (`src/services/user/account.ts`) now accepts optional `deviceName`, `deviceToken`, `platform` on `PasswordResetProps` and returns `Promise<AuthResponse | null>` instead of `Promise<void>`, so mobile can pass device info and receive a session back from the reset call.
+- `listOAuthProviders` and `unlinkOAuthProvider` (`src/services/user/session.ts`) now read `userId` from `globalConfig.sessionConfig.userId`.
+
+## Alternatives Considered
+No alternatives considered.
+
+## Process Notes
+Initial implementation had a bug: the request body sent `token: props.password` instead of `token: props.token`, which would have sent the user's new password as the reset token. Caught and fixed before opening the PR.
+
+## Consequences
+- `resetPassword` callers must handle the new return type (`AuthResponse | null`) instead of `void`.
+- Mobile clients can now log in immediately after a password reset without a separate auth call.
+- OAuth provider list/unlink calls no longer resolve `userId` as `undefined`.

package/.claude/settings.local.json

@@ -0,0 +1,71 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(npx jest *)",
+      "Bash(npx tsc *)",
+      "Skill(counselors)",
+      "Bash(counselors ls *)",
+      "Bash(counselors groups *)",
+      "Bash(counselors run *)",
+      "Bash(npm test *)",
+      "Bash(gh pr *)",
+      "Bash(gh api *)",
+      "Bash(mkdir -p /tmp/pr-review-v2)",
+      "Read(//tmp/pr-review-v2/**)",
+      "Bash(cat /home/alesevero/railenvironment/applications/musora-content-services/AGENTS.md)",
+      "Bash(echo \"no AGENTS.md\")",
+      "Bash(echo \"exit=$?\")",
+      "Bash(git checkout *)",
+      "Skill(pr)",
+      "Skill(create-decision)",
+      "mcp__github__pull_request_read",
+      "mcp__github__push_files",
+      "Bash(git push *)",
+      "mcp__github__create_pull_request",
+      "mcp__github__search_pull_requests",
+      "Bash(git commit *)",
+      "Bash(git add *)",
+      "mcp__github__list_pull_requests",
+      "mcp__sanity__get_schema",
+      "mcp__sanity__query_documents",
+      "Bash(git rm *)",
+      "Bash(git rebase *)",
+      "Bash(git fetch *)",
+      "Bash(git --no-pager log --oneline -1)",
+      "Bash(git --no-pager log --oneline -5)",
+      "Bash(git ls-tree *)",
+      "Bash(git --no-pager log --oneline -2)",
+      "Bash(git --no-pager diff --stat HEAD~1)",
+      "Bash(git check-ignore *)",
+      "Bash(python3 -)",
+      "Bash(git --no-pager log --oneline -3)",
+      "Bash(mkdir *)",
+      "Bash(git --no-pager log --oneline origin/main..HEAD)"
+    ]
+  },
+  "model": "sonnet",
+  "enabledMcpjsonServers": [
+    "atlassian",
+    "figma",
+    "google-workspace",
+    "snowflake",
+    "aws",
+    "hex",
+    "sanity",
+    "mysql",
+    "slack",
+    "langfuse",
+    "chrome-devtools",
+    "railway",
+    "github",
+    "asana"
+  ],
+  "disabledMcpjsonServers": [
+    "nightwatch",
+    "1password",
+    "mysql-staging",
+    "mysql-local",
+    "mobile"
+  ],
+  "effortLevel": "medium"
+}

package/CHANGELOG.md

@@ -2,6 +2,21 @@
 
 All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines.
 
+## [2.177.0](https://github.com/railroadmedia/musora-content-services/compare/v2.176.0...v2.177.0) (2026-08-19)
+
+
+### Features
+
+* make built GROQ queries runnable with a typed result ([#1036](https://github.com/railroadmedia/musora-content-services/issues/1036)) ([70b45bc](https://github.com/railroadmedia/musora-content-services/commit/70b45bc446d08ce97ac8708840b205c7c35cb5b7)), closes [#1034](https://github.com/railroadmedia/musora-content-services/issues/1034)
+* **query:** add composite() for multi-key GROQ projections ([#1034](https://github.com/railroadmedia/musora-content-services/issues/1034)) ([ea4f2ca](https://github.com/railroadmedia/musora-content-services/commit/ea4f2caf84a59b7a737b7f1ff9e6c9dc32942810))
+
+
+### Bug Fixes
+
+* **BEH-1590:** login as user on mobile app ([#1033](https://github.com/railroadmedia/musora-content-services/issues/1033)) ([a5f9ef4](https://github.com/railroadmedia/musora-content-services/commit/a5f9ef41ab42b04f961d53bc4cd8e29a89dc4b2b))
+* escape values interpolated into GROQ filter strings ([#1035](https://github.com/railroadmedia/musora-content-services/issues/1035)) ([bc34d4b](https://github.com/railroadmedia/musora-content-services/commit/bc34d4bef8a33a25ea7e93fa51d7d415aefcfe69)), closes [#1034](https://github.com/railroadmedia/musora-content-services/issues/1034)
+* password reset mobile token and sessionConfig access ([#1031](https://github.com/railroadmedia/musora-content-services/issues/1031)) ([0f7633c](https://github.com/railroadmedia/musora-content-services/commit/0f7633c23cd03d9402347200dd66d6243e8a66c5))
+
 ## [2.176.0](https://github.com/railroadmedia/musora-content-services/compare/v2.175.0...v2.176.0) (2026-08-18)
 
 

package/jest.config.js

@@ -38,6 +38,8 @@ export default {
     '!src/services/user/interests.js',
     '!src/services/user/payments.ts',
     '!src/services/user/chat.js',
+    '!src/**/examples.ts',
+    '!src/**/examples/**',
   ],
 
   // The directory where Jest should output its coverage files
@@ -165,10 +167,9 @@ export default {
     'dotenv/config',
     '<rootDir>/test/setupConsole.js',
     '<rootDir>/test/setupNetworkGuard.js',
-    '<rootDir>/test/setupTimers.js'
+    '<rootDir>/test/setupTimers.js',
   ],
 
-
   // The number of seconds after which a test is considered as slow and reported as such in the results.
   // slowTestThreshold: 5,
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "musora-content-services",
-  "version": "2.176.0",
+  "version": "2.177.0",
   "description": "A package for Musoras content services ",
   "main": "src/index.js",
   "type": "module",

package/src/index.d.ts

@@ -494,6 +494,7 @@ import {
 
 import {
 	listOAuthProviders,
+	loginAsUser,
 	redirectToOAuthProvider,
 	unlinkOAuthProvider,
 	verifyOAuthToken
@@ -805,6 +806,7 @@ declare module 'musora-content-services' {
 		listOAuthProviders,
 		lockThread,
 		login,
+		loginAsUser,
 		logout,
 		mapContentToParent,
 		markAllNotificationsAsRead,

package/src/index.js

@@ -498,6 +498,7 @@ import {
 
 import {
 	listOAuthProviders,
+	loginAsUser,
 	redirectToOAuthProvider,
 	unlinkOAuthProvider,
 	verifyOAuthToken
@@ -804,6 +805,7 @@ export {
 	listOAuthProviders,
 	lockThread,
 	login,
+	loginAsUser,
 	logout,
 	mapContentToParent,
 	markAllNotificationsAsRead,

package/src/lib/ads/coproduct.ts

@@ -0,0 +1,184 @@
+import { Droppable } from './interfaces/droppable'
+import { DisjointFoldable2 } from './interfaces/foldable'
+import { Recoverable } from './interfaces/recoverable'
+import { Tappable } from './interfaces/tappable'
+import { Monad } from './monad'
+
+/** A monadic container that represents a value that can be either a left or a right value. */
+export abstract class Coproduct<L, R>
+  implements
+    Tappable<L | R>,
+    DisjointFoldable2<L, R>,
+    Droppable<L | R>,
+    Recoverable<R>,
+    Monad<L | R>
+{
+  static left<L, R>(value: L): Coproduct<L, R> {
+    return new Left(value)
+  }
+
+  static right<L, R>(value: R): Coproduct<L, R> {
+    return new Right(value)
+  }
+
+  abstract isLeft(): this is Left<L, R>
+  abstract isRight(): this is Right<L, R>
+
+  /**
+   * @extends Functor
+   * Maps the right value of the Coproduct.
+   */
+  abstract map<T>(fn: (r: R) => T): Coproduct<L, T>
+  /**
+   * Maps the right value of the Coproduct with an asynchronous function.
+   * A rejection propagates: there is no way to build an L from it.
+   */
+  abstract mapAsync<T>(fn: (r: R) => Promise<T>): Promise<Coproduct<L, T>>
+  /**
+   * @extends Monad
+   * Applies a function to the right value of the Coproduct, returning a new Coproduct.
+   */
+  abstract flatMap<T>(fn: (r: R) => Coproduct<L, T>): Coproduct<L, T>
+
+  /** Maps the left value of the Coproduct to a new type. */
+  abstract mapLeft<T>(fn: (l: L) => T): Coproduct<T, R>
+
+  /** Applies a function to the left value of the Coproduct, returning a new Coproduct. */
+  abstract flatMapLeft<T>(fn: (l: L) => Coproduct<T, R>): Coproduct<T, R>
+
+  abstract fold<T, U>(onLeft: (l: L) => T, onRight: (r: R) => U): T | U
+  foldMap<T>(initial: T, fn: (acc: T, value: L | R) => T): T {
+    return this.fold(
+      (l) => fn(initial, l),
+      (r) => fn(initial, r)
+    )
+  }
+
+  /**
+   * Visits the value inside the container if right and applies a function to it without modifying
+   * @implements Tappable
+   */
+  abstract tap(fn: (r: R) => void): this
+
+  /** Visits the value inside the container if left and applies a function to it without modifying */
+  abstract ltap(fn: (l: L) => void): Coproduct<L, R>
+  abstract drop(): R | L
+  /**
+   * Returns the right value if it exists, otherwise returns the provided default value.
+   * @implements Recoverable
+   */
+  abstract recover(defaultValue: R): R
+}
+
+export class Left<L, R> extends Coproduct<L, R> {
+  constructor(private readonly value: L) {
+    super()
+  }
+
+  isLeft(): this is Left<L, R> {
+    return true
+  }
+
+  isRight(): this is Right<L, R> {
+    return false
+  }
+
+  map<T>(_fn: (r: R) => T): Coproduct<L, T> {
+    return new Left(this.value)
+  }
+
+  async mapAsync<T>(_fn: (r: R) => Promise<T>): Promise<Coproduct<L, T>> {
+    return new Left(this.value)
+  }
+
+  flatMap<T>(_fn: (r: R) => Coproduct<L, T>): Coproduct<L, T> {
+    return new Left(this.value)
+  }
+
+  mapLeft<T>(fn: (l: L) => T): Coproduct<T, R> {
+    return new Left(fn(this.value))
+  }
+
+  flatMapLeft<T>(fn: (l: L) => Coproduct<T, R>): Coproduct<T, R> {
+    return fn(this.value)
+  }
+
+  fold<T, U>(onLeft: (l: L) => T, _onRight: (r: R) => U): T | U {
+    return onLeft(this.value)
+  }
+
+  tap(_fn: (l: R) => void): this {
+    return this
+  }
+
+  ltap(fn: (l: L) => void): Coproduct<L, R> {
+    const valueToTap = this.value
+    fn(valueToTap)
+    return this
+  }
+
+  drop(): L | R {
+    return this.value
+  }
+
+  recover(defaultValue: R): R {
+    return defaultValue
+  }
+}
+
+/** A right value in an Coproduct, usually representing a success or valid result. */
+export class Right<L, R> extends Coproduct<L, R> {
+  constructor(private readonly value: R) {
+    super()
+  }
+
+  isLeft(): this is Left<L, R> {
+    return false
+  }
+
+  isRight(): this is Right<L, R> {
+    return true
+  }
+
+  map<T>(fn: (r: R) => T): Coproduct<L, T> {
+    return new Right(fn(this.value))
+  }
+
+  async mapAsync<T>(fn: (r: R) => Promise<T>): Promise<Coproduct<L, T>> {
+    return new Right(await fn(this.value))
+  }
+
+  flatMap<T>(fn: (r: R) => Coproduct<L, T>): Coproduct<L, T> {
+    return fn(this.value)
+  }
+
+  mapLeft<T>(_fn: (l: L) => T): Coproduct<T, R> {
+    return new Right(this.value)
+  }
+
+  flatMapLeft<T>(_fn: (l: L) => Coproduct<T, R>): Coproduct<T, R> {
+    return new Right(this.value)
+  }
+
+  fold<T, U>(_onLeft: (l: L) => T, onRight: (r: R) => U): T | U {
+    return onRight(this.value)
+  }
+
+  tap(fn: (r: R) => void): this {
+    const valueToTap = this.value
+    fn(valueToTap)
+    return this
+  }
+
+  ltap(_fn: (l: L) => void): Coproduct<L, R> {
+    return this
+  }
+
+  drop(): L | R {
+    return this.value
+  }
+
+  recover(_defaultValue: R): R {
+    return this.drop() as R
+  }
+}

package/src/lib/ads/either.ts

@@ -0,0 +1,9 @@
+import { Coproduct } from './coproduct'
+
+/** A Coproduct under the convention that left carries the error and right carries the success value. */
+export type Either<L, R> = Coproduct<L, R>
+
+export const Either = {
+  left: Coproduct.left,
+  right: Coproduct.right,
+}

package/src/lib/ads/functor.ts

@@ -0,0 +1,9 @@
+export abstract class Functor<T> {
+  /** Applies a function to the value inside the functor */
+  abstract map<U>(fn: (value: T) => U): Functor<U>
+
+  /** Lifts a value into a Functor*/
+  static of<T>(_value: T): Functor<T> {
+    throw new Error('Method not implemented. Use a subclass of Functor.')
+  }
+}

package/src/lib/ads/interfaces/droppable.ts

@@ -0,0 +1,4 @@
+export interface Droppable<T> {
+  /** Drops the value out of the container and returns it. */
+  drop(): T
+}

package/src/lib/ads/interfaces/foldable.ts

@@ -0,0 +1,24 @@
+export interface Foldable<A> {
+  /**
+   * Folds the values in the container using the provided function.
+   * Similar to reduce for collections (arrays/lists/trees)
+   */
+  foldMap<T>(initial: T, fn: (acc: T, value: A) => T): T
+}
+
+/** FoldableProduct is a specialized Foldable for containers that hold two values, like a tuple. */
+export interface FoldableProduct<F, S> extends Foldable<F | S> {
+  fold<T>(fn: (first: F, second: S) => T): T
+}
+
+/** DisjointFoldable is a specialized Foldable for containers that can hold either a single value or none, like Maybe. */
+export interface DisjointFoldable1<A> extends Foldable<A> {
+  /** Folds the values in the container using the provided function. */
+  fold<T>(onNone: () => T, onSome: (a: A) => T): T
+}
+
+/** DisjointFoldable2 is a specialized Foldable for containers that can hold either a left or right value, like Either. */
+export interface DisjointFoldable2<L, R> extends Foldable<L | R> {
+  /** Folds the values in the container using the provided functions for left and right. */
+  fold<T>(onLeft: (l: L) => T, onRight: (r: R) => T): T
+}

package/src/lib/ads/interfaces/recoverable.ts

@@ -0,0 +1,4 @@
+export interface Recoverable<T> {
+  /** Recovers the value from the container, providing a default value if the container is empty or contains lefty values. */
+  recover(defaultValue: T): T
+}

package/src/lib/ads/interfaces/tappable.ts

@@ -0,0 +1,4 @@
+export interface Tappable<V> {
+  /** Visits the value inside the container and applies a function to it without modifying. */
+  tap(fn: (value: V) => void): this
+}

package/src/lib/ads/monad.ts

@@ -0,0 +1,6 @@
+import { Functor } from './functor'
+
+export abstract class Monad<T> extends Functor<T> {
+  /** Applies a function to the value inside the monad, returning a new monad. */
+  abstract flatMap<U>(fn: (value: T) => Monad<U>): Monad<U>
+}

package/src/lib/sanity/examples.ts

@@ -0,0 +1,204 @@
+import { Filters as f } from './filter'
+import { decorateAll, type FieldDecorator } from './decorators/base'
+import { accessDecorator, decorateAccess } from './decorators/need-access'
+import { lifetimeUpgradeDecorator } from './decorators/need-lifetime-upgrade'
+import { pageTypeDecorator } from './decorators/page-type'
+import { decorateNavigateTo } from './decorators/navigate-to'
+import { fetchUserPermissions, type UserPermissions } from '../../services/permissions'
+import { groq } from './groq'
+import { composite, query } from './query'
+import { run, sanityRunner, QueryRunner, SanityQueryError } from './runner'
+import { Either } from '../ads/either'
+
+interface Song {
+  _id: string
+  title: string
+  railcontent_id: number
+}
+
+interface SongPage {
+  data: Song[]
+  total: number
+}
+
+const publishedSongs = (brand: string) =>
+  f.combine(f.type('song'), f.statusIn(['published']), f.defined('railcontent_id'), f.brand(brand))
+
+export async function fetchSongTitles(brand: string) {
+  const result = await groq()
+    .and(publishedSongs(brand))
+    .order('published_on desc')
+    .slice(0, 10)
+    .select('_id', 'title', 'railcontent_id')
+    .run<Song[]>()
+
+  return result.fold(
+    (error) => {
+      console.error(`${error.name}: ${error.message}`, error.groq)
+      return []
+    },
+    (songs) => songs ?? []
+  )
+}
+
+export async function fetchSongPage(brand: string, offset: number, limit: number) {
+  const restrictions = publishedSongs(brand)
+
+  const result = await groq
+    .composite({
+      data: query()
+        .and(restrictions)
+        .order('published_on desc')
+        .slice(offset, limit)
+        .select('_id', 'title', 'railcontent_id'),
+      total: f.count(restrictions),
+    })
+    .run<SongPage>()
+
+  return result.recover({ data: [], total: 0 })
+}
+
+export async function countSongsAndLessons(brand: string) {
+  const result = await run<{ songs: number; lessons: number }>(
+    composite({
+      songs: f.count(f.combine(f.type('song'), f.brand(brand))),
+      lessons: f.count(f.combine(f.typeIn(['course', 'quick-tips']), f.brand(brand))),
+    })
+  )
+
+  return result
+    .map((counts) => counts ?? { songs: 0, lessons: 0 })
+    .map((counts) => ({ ...counts, total: counts.songs + counts.lessons }))
+    .recover({ songs: 0, lessons: 0, total: 0 })
+}
+
+export async function reportMissingSongs(brand: string) {
+  const result = await groq().and(publishedSongs(brand)).run<Song[]>()
+
+  if (result.isRight()) {
+    return result.drop()
+  }
+
+  return null
+}
+
+export async function fetchWithSharedClient(groqQueries: string[], runner: QueryRunner<Song[]>) {
+  return Promise.all(groqQueries.map((groq) => run<Song[]>(groq, runner)))
+}
+
+export function buildRunnerForTests(): QueryRunner<Song[]> {
+  return async () => Either.right<SanityQueryError, Song[]>([])
+}
+
+export const productionRunner = sanityRunner()
+
+interface Lesson {
+  id: number
+  type: string
+  brand: string
+  thumbnail: string
+  published_on: string | null
+  status: string
+  permission_id?: number[]
+  children?: Lesson[]
+  [key: string]: unknown
+}
+
+export async function fetchLessonsWithoutPermissions(brand: string) {
+  const result = await groq().and(f.brand(brand)).slice(0, 10).run<Lesson[]>()
+
+  return result
+    .map((lessons) =>
+      decorateAll<Lesson>(lessons ?? [], [pageTypeDecorator as FieldDecorator<Lesson>])
+    )
+    .recover([])
+}
+
+export async function fetchDecoratedLessons(brand: string) {
+  const [result, permissions] = await Promise.all([
+    groq()
+      .and(f.combine(f.typeIn(['course']), f.brand(brand)))
+      .slice(0, 10)
+      .run<Lesson[]>(),
+    fetchUserPermissions(),
+  ])
+
+  return result
+    .map((lessons) =>
+      decorateAll<Lesson>(lessons ?? [], [
+        accessDecorator(permissions) as FieldDecorator<Lesson>,
+        lifetimeUpgradeDecorator(permissions) as FieldDecorator<Lesson>,
+        pageTypeDecorator as FieldDecorator<Lesson>,
+      ])
+    )
+    .recover([])
+}
+
+export async function fetchLessonsWithNavigation(brand: string) {
+  const [result, permissions] = await Promise.all([
+    groq().and(f.brand(brand)).slice(0, 10).run<Lesson[]>(),
+    fetchUserPermissions(),
+  ])
+
+  const decorated = await result
+    .map((lessons) =>
+      decorateAll<Lesson>(lessons ?? [], [accessDecorator(permissions) as FieldDecorator<Lesson>])
+    )
+    .mapAsync((lessons) => decorateNavigateTo(lessons) as Promise<Lesson[]>)
+
+  return decorated.recover([])
+}
+
+export async function fetchWithACustomDecorator(brand: string) {
+  const isFree: FieldDecorator<Lesson> = {
+    field: 'is_free',
+    compute: (lesson) => lesson.permission_id === undefined,
+  }
+
+  const result = await groq().and(f.brand(brand)).run<Lesson[]>()
+
+  return result.map((lessons) => decorateAll<Lesson>(lessons ?? [], [isFree])).recover([])
+}
+
+export async function fetchWhenPermissionsMayBeUnavailable(brand: string) {
+  const queryError = (error: unknown) =>
+    Either.left<SanityQueryError, UserPermissions>(
+      new SanityQueryError('Failed to fetch user permissions', '', error)
+    )
+
+  const [result, permissions] = await Promise.all([
+    groq().and(f.brand(brand)).run<Lesson[]>(),
+    fetchUserPermissions()
+      .then(Either.right<SanityQueryError, UserPermissions>)
+      .catch(queryError),
+  ])
+
+  return result
+    .flatMap((lessons) =>
+      permissions.map((userPermissions) =>
+        decorateAll<Lesson>(lessons ?? [], [
+          accessDecorator(userPermissions) as FieldDecorator<Lesson>,
+        ])
+      )
+    )
+    .fold(
+      (error) => `undecorated: ${error.message}`,
+      (lessons) => `${lessons.length} lessons`
+    )
+}
+
+export async function decorateManuallyForPreciseTypes(brand: string) {
+  const [result, permissions] = await Promise.all([
+    groq().and(f.brand(brand)).slice(0, 10).run<Lesson[]>(),
+    fetchUserPermissions(),
+  ])
+
+  const decorated = await result
+    .map((lessons) => decorateAccess(lessons ?? [], permissions))
+    .mapAsync((lessons) => decorateNavigateTo(lessons))
+
+  return decorated.fold(
+    () => [],
+    (lessons) => lessons.map((lesson) => [lesson.need_access, lesson.navigateTo] as const)
+  )
+}