@strav/social 1.0.0-alpha.22 → 1.0.0-alpha.24

package/package.json

@@ -1,15 +1,15 @@
 {
   "name": "@strav/social",
-  "version": "1.0.0-alpha.22",
+  "version": "1.0.0-alpha.24",
   "description": "Strav social-login module — provider-agnostic OAuth/OIDC client. Normalized profile + token DTOs, state + PKCE helpers, capability gating, multi-provider routing. Line / Google / Facebook adapters ship as subpath imports (`@strav/social/line`, `@strav/social/google`, `@strav/social/facebook`).",
   "type": "module",
   "main": "./src/index.ts",
   "types": "./src/index.ts",
   "exports": {
     ".": "./src/index.ts",
-    "./line": "./src/line/index.ts",
-    "./google": "./src/google/index.ts",
-    "./facebook": "./src/facebook/index.ts",
+    "./line": "./src/drivers/line/index.ts",
+    "./google": "./src/drivers/google/index.ts",
+    "./facebook": "./src/drivers/facebook/index.ts",
     "./tenanted": "./src/tenanted/index.ts"
   },
   "files": [
@@ -23,9 +23,9 @@
     "access": "public"
   },
   "dependencies": {
-    "@strav/database": "1.0.0-alpha.22",
-    "@strav/http": "1.0.0-alpha.22",
-    "@strav/kernel": "1.0.0-alpha.22"
+    "@strav/database": "1.0.0-alpha.24",
+    "@strav/http": "1.0.0-alpha.24",
+    "@strav/kernel": "1.0.0-alpha.24"
   },
   "peerDependencies": {
     "@types/bun": ">=1.3.14"

package/src/{facebook → drivers/facebook}/facebook_config.ts

@@ -9,7 +9,7 @@
  * going to production.
  */
 
-import type { ProviderConfig } from '../types.ts'
+import type { ProviderConfig } from '../../types.ts'
 
 export interface FacebookProviderConfig extends ProviderConfig {
   driver: 'facebook'

package/src/{facebook → drivers/facebook}/facebook_driver.ts

@@ -33,23 +33,23 @@
  *     Graph API directly.
  */
 
-import type { OAuthTokens, SocialProfile } from '../dto/index.ts'
-import type { SocialCapability } from '../social_capabilities.ts'
+import type { OAuthTokens, SocialProfile } from '../../dto/index.ts'
+import type { SocialCapability } from '../../social_capabilities.ts'
 import type {
   AuthorizeInput,
   AuthorizeResult,
   ExchangeInput,
   RefreshInput,
   SocialDriver,
-} from '../social_driver.ts'
+} from '../../social_driver.ts'
 import {
   InvalidTokenError,
   OAuthExchangeError,
   ProviderUnsupportedError,
   SocialProviderError,
   StateMismatchError,
-} from '../social_error.ts'
-import { codeChallengeFor, randomCodeVerifier, randomState } from '../pkce.ts'
+} from '../../social_error.ts'
+import { codeChallengeFor, randomCodeVerifier, randomState } from '../../pkce.ts'
 import {
   DEFAULT_FACEBOOK_PROFILE_FIELDS,
   facebookEndpoints,

package/src/{facebook → drivers/facebook}/facebook_provider.ts

@@ -4,8 +4,8 @@
  */
 
 import { type Application, ServiceProvider } from '@strav/kernel'
-import { SocialConfigError } from '../social_error.ts'
-import { SocialManager } from '../social_manager.ts'
+import { SocialConfigError } from '../../social_error.ts'
+import { SocialManager } from '../../social_manager.ts'
 import type { FacebookProviderConfig } from './facebook_config.ts'
 import { FacebookSocialDriver } from './facebook_driver.ts'
 

package/src/{google → drivers/google}/google_config.ts

@@ -11,7 +11,7 @@
  * enforced per-authorize via `authorize({ extra: { hd: 'example.com' } })`.
  */
 
-import type { ProviderConfig } from '../types.ts'
+import type { ProviderConfig } from '../../types.ts'
 
 export interface GoogleProviderConfig extends ProviderConfig {
   driver: 'google'

package/src/{google → drivers/google}/google_driver.ts

@@ -32,22 +32,22 @@
  *     consent to one Workspace domain.
  */
 
-import type { OAuthTokens, SocialProfile } from '../dto/index.ts'
-import type { SocialCapability } from '../social_capabilities.ts'
+import type { OAuthTokens, SocialProfile } from '../../dto/index.ts'
+import type { SocialCapability } from '../../social_capabilities.ts'
 import type {
   AuthorizeInput,
   AuthorizeResult,
   ExchangeInput,
   RefreshInput,
   SocialDriver,
-} from '../social_driver.ts'
+} from '../../social_driver.ts'
 import {
   InvalidTokenError,
   OAuthExchangeError,
   SocialProviderError,
   StateMismatchError,
-} from '../social_error.ts'
-import { codeChallengeFor, randomCodeVerifier, randomState } from '../pkce.ts'
+} from '../../social_error.ts'
+import { codeChallengeFor, randomCodeVerifier, randomState } from '../../pkce.ts'
 import { GOOGLE_ENDPOINTS, type GoogleProviderConfig } from './google_config.ts'
 
 const PROVIDER = 'google'

package/src/{google → drivers/google}/google_provider.ts

@@ -8,8 +8,8 @@
  */
 
 import { type Application, ServiceProvider } from '@strav/kernel'
-import { SocialConfigError } from '../social_error.ts'
-import { SocialManager } from '../social_manager.ts'
+import { SocialConfigError } from '../../social_error.ts'
+import { SocialManager } from '../../social_manager.ts'
 import type { GoogleProviderConfig } from './google_config.ts'
 import { GoogleSocialDriver } from './google_driver.ts'
 

package/src/{line → drivers/line}/line_config.ts

@@ -8,7 +8,7 @@
  * inside the channel (Line approval required for production).
  */
 
-import type { ProviderConfig } from '../types.ts'
+import type { ProviderConfig } from '../../types.ts'
 
 export interface LineProviderConfig extends ProviderConfig {
   driver: 'line'

package/src/{line → drivers/line}/line_driver.ts

@@ -29,22 +29,22 @@
  * Token / refresh / revoke all use the standard OAuth2 endpoints.
  */
 
-import type { OAuthTokens, SocialProfile } from '../dto/index.ts'
-import type { SocialCapability } from '../social_capabilities.ts'
+import type { OAuthTokens, SocialProfile } from '../../dto/index.ts'
+import type { SocialCapability } from '../../social_capabilities.ts'
 import type {
   AuthorizeInput,
   AuthorizeResult,
   ExchangeInput,
   RefreshInput,
   SocialDriver,
-} from '../social_driver.ts'
+} from '../../social_driver.ts'
 import {
   InvalidTokenError,
   OAuthExchangeError,
   SocialProviderError,
   StateMismatchError,
-} from '../social_error.ts'
-import { codeChallengeFor, randomCodeVerifier, randomState } from '../pkce.ts'
+} from '../../social_error.ts'
+import { codeChallengeFor, randomCodeVerifier, randomState } from '../../pkce.ts'
 import { LINE_ENDPOINTS, type LineProviderConfig } from './line_config.ts'
 
 const PROVIDER = 'line'

package/src/{line → drivers/line}/line_provider.ts

@@ -9,8 +9,8 @@
  */
 
 import { type Application, ServiceProvider } from '@strav/kernel'
-import { SocialConfigError } from '../social_error.ts'
-import { SocialManager } from '../social_manager.ts'
+import { SocialConfigError } from '../../social_error.ts'
+import { SocialManager } from '../../social_manager.ts'
 import type { LineProviderConfig } from './line_config.ts'
 import { LineSocialDriver } from './line_driver.ts'
 

package/src/ledger/social_account_repository.ts

@@ -26,10 +26,8 @@
  * encrypt/decrypt throws `ConfigError`.
  */
 
-// biome-ignore lint/style/useImportType: PostgresDatabase + SchemaRegistry value imports for @inject() metadata.
-import { PostgresDatabase, quoteIdent, Repository, SchemaRegistry } from '@strav/database'
-// biome-ignore lint/style/useImportType: Cipher + EventBus value imports for @inject() metadata.
-import { Cipher, EventBus, inject, ulid } from '@strav/kernel'
+import { quoteIdent, Repository } from '@strav/database'
+import { ulid } from '@strav/kernel'
 import type { OAuthTokens, SocialProfile } from '../dto/index.ts'
 import { SocialAccount } from './social_account.ts'
 import { socialAccountSchema } from './social_account_schema.ts'
@@ -48,21 +46,10 @@ export interface DisconnectInput {
   provider: string
 }
 
-@inject()
 export class SocialAccountRepository extends Repository<SocialAccount> {
   static override readonly schema = socialAccountSchema
   static override readonly model = SocialAccount
 
-  // biome-ignore lint/complexity/noUselessConstructor: explicit constructor forces TS to emit `design:paramtypes` for @inject(). The fourth param is the Cipher for @encrypt token columns — apps must register EncryptionProvider before this repository resolves.
-  constructor(
-    db: PostgresDatabase,
-    events: EventBus,
-    registry?: SchemaRegistry,
-    cipher?: Cipher,
-  ) {
-    super(db, events, registry, cipher)
-  }
-
   /**
    * Upsert a social account by `(provider, provider_user_id)`.
    * Insert on first link; update tokens + cached profile fields

package/src/social_driver.ts

@@ -5,10 +5,48 @@
  * (`config.social.providers[name]`). The manager holds one
  * driver per configured name and routes calls into it.
  *
- * Methods drivers don't support throw `ProviderUnsupportedError`
- * synchronously. The driver's `capabilities` set declares the
- * supported feature set — apps that branch on capability avoid
- * the throw by checking first.
+ * ## Capability gating — the "honest LSP violation" pattern
+ *
+ * Strictly speaking, the interface below violates Liskov substitution
+ * because `FacebookSocialDriver.refresh()` throws synchronously instead
+ * of returning `Promise<OAuthTokens>` (Facebook doesn't issue refresh
+ * tokens). Same shape for any future driver that lacks an operation
+ * its interface declares.
+ *
+ * The framework prefers this trade-off over the alternative (every
+ * provider gets its own narrowed sub-interface, every app does a
+ * `if (isRefreshable(driver))` narrowing dance) for three reasons:
+ *
+ *   1. **Discoverability**: apps see ONE `SocialDriver` interface
+ *      with all the operations a sign-in flow needs. They learn the
+ *      surface once, not per-adapter.
+ *
+ *   2. **Capability flags are the typed truth**: each driver
+ *      declares `capabilities: ReadonlySet<SocialCapability>`. Apps
+ *      that care about portability check the flag and branch — the
+ *      `unsupported` throw becomes the safety net for callers who
+ *      forgot, not the primary API.
+ *
+ *   3. **Failures are loud and synchronous**. Drivers use the
+ *      `unsupported(provider, op, reason?)` helper so the throw
+ *      happens on the function call, NOT after a network round-trip
+ *      had a chance to bill the user / consume rate limit. Apps fail
+ *      fast.
+ *
+ * Apps that want compile-time safety against unsupported ops wrap the
+ * driver themselves:
+ *
+ * ```ts
+ * function refreshableDriver(d: SocialDriver) {
+ *   if (!d.capabilities.has('tokens.refresh')) return null
+ *   return d  // narrowed by convention; refresh() is now safe to call.
+ * }
+ * ```
+ *
+ * A split into `SocialDriver` + `RefreshableSocialDriver` + ... may
+ * land later (`docs/code-quality.md` action item #4) — but doing so
+ * carries the manager's `use(name): SocialDriver` return type through
+ * a wider refactor. Until then, the capability set IS the contract.
  */
 
 import type { OAuthTokens, SocialProfile } from './dto/index.ts'

package/src/tenanted/tenanted_social_account_repository.ts

@@ -11,10 +11,8 @@
  * branching on a tenancy flag.
  */
 
-// biome-ignore lint/style/useImportType: PostgresDatabase value import for @inject() metadata.
-import { PostgresDatabase, quoteIdent, Repository, SchemaRegistry } from '@strav/database'
-// biome-ignore lint/style/useImportType: Cipher + EventBus value imports for @inject() metadata.
-import { Cipher, EventBus, inject, ulid } from '@strav/kernel'
+import { quoteIdent, Repository } from '@strav/database'
+import { ulid } from '@strav/kernel'
 import type { OAuthTokens, SocialProfile } from '../dto/index.ts'
 import { SocialAccountAlreadyLinkedError } from '../ledger/social_account_repository.ts'
 import { TenantedSocialAccount } from './tenanted_social_account.ts'
@@ -32,21 +30,10 @@ export interface DisconnectInput {
   provider: string
 }
 
-@inject()
 export class TenantedSocialAccountRepository extends Repository<TenantedSocialAccount> {
   static override readonly schema = tenantedSocialAccountSchema
   static override readonly model = TenantedSocialAccount
 
-  // biome-ignore lint/complexity/noUselessConstructor: explicit constructor forces TS to emit `design:paramtypes` for @inject(). The fourth param is the Cipher for @encrypt token columns.
-  constructor(
-    db: PostgresDatabase,
-    events: EventBus,
-    registry?: SchemaRegistry,
-    cipher?: Cipher,
-  ) {
-    super(db, events, registry, cipher)
-  }
-
   async connect(input: ConnectInput): Promise<TenantedSocialAccount> {
     const existing = await this.findByProviderIdentity(
       input.provider,