@audius/sdk 15.0.1 → 15.3.0

package/src/sdk/oauth/tokenStoreLocalStorage.test.ts

@@ -34,6 +34,8 @@ describe('TokenStoreLocalStorage — localStorage persistence', () => {
     const store = new TokenStoreLocalStorage()
     expect(await store.getAccessToken()).toBeNull()
     expect(await store.getRefreshToken()).toBeNull()
+    expect(await store.getAccessTokenExpiry()).toBeNull()
+    expect(await store.getRefreshTokenExpiry()).toBeNull()
   })
 
   it('setTokens writes to localStorage', async () => {
@@ -49,7 +51,43 @@ describe('TokenStoreLocalStorage — localStorage persistence', () => {
     )
   })
 
-  it('clear removes tokens from localStorage', async () => {
+  it('setTokens writes expiry keys when provided', async () => {
+    const store = new TokenStoreLocalStorage()
+    await store.setTokens('at', 'rt', 3600, 2592000)
+    expect(mockLocalStorage.setItem).toHaveBeenCalledWith(
+      'audius_access_token_expiry',
+      expect.any(String)
+    )
+    expect(mockLocalStorage.setItem).toHaveBeenCalledWith(
+      'audius_refresh_token_expiry',
+      expect.any(String)
+    )
+  })
+
+  it('setTokens removes expiry keys when not provided', async () => {
+    const store = new TokenStoreLocalStorage()
+    await store.setTokens('at', 'rt')
+    expect(mockLocalStorage.removeItem).toHaveBeenCalledWith(
+      'audius_access_token_expiry'
+    )
+    expect(mockLocalStorage.removeItem).toHaveBeenCalledWith(
+      'audius_refresh_token_expiry'
+    )
+  })
+
+  it('reads persisted expiry from localStorage', async () => {
+    const futureMs = String(Date.now() + 3600000)
+    mockLocalStorage.getItem.mockImplementation((key: string) => {
+      if (key === 'audius_access_token_expiry') return futureMs
+      if (key === 'audius_refresh_token_expiry') return futureMs
+      return null
+    })
+    const store = new TokenStoreLocalStorage()
+    expect(await store.getAccessTokenExpiry()).toBe(Number(futureMs))
+    expect(await store.getRefreshTokenExpiry()).toBe(Number(futureMs))
+  })
+
+  it('clear removes all keys from localStorage', async () => {
     const store = new TokenStoreLocalStorage()
     await store.setTokens('at', 'rt')
     await store.clear()
@@ -59,5 +97,11 @@ describe('TokenStoreLocalStorage — localStorage persistence', () => {
     expect(mockLocalStorage.removeItem).toHaveBeenCalledWith(
       'audius_refresh_token'
     )
+    expect(mockLocalStorage.removeItem).toHaveBeenCalledWith(
+      'audius_access_token_expiry'
+    )
+    expect(mockLocalStorage.removeItem).toHaveBeenCalledWith(
+      'audius_refresh_token_expiry'
+    )
   })
 })

package/src/sdk/scripts/generateServicesConfig.ts

@@ -9,7 +9,6 @@ import {
   ServiceProviderFactory,
   ServiceTypeManager
 } from '@audius/eth'
-import range from 'lodash/range.js'
 import { createPublicClient, hexToString, http } from 'viem'
 import { mainnet } from 'viem/chains'
 
@@ -148,7 +147,7 @@ const generateServicesConfig = async (
       args: [serviceType]
     })
     const list = await Promise.all(
-      range(1, Number(count) + 1).map((i) =>
+      Array.from({ length: Number(count) }, (_, i) => i + 1).map((i) =>
         ethPublicClient.readContract({
           address: spfAddress,
           abi: ServiceProviderFactory.abi,

package/src/sdk/services/EntityManager/EntityManagerClient.ts

@@ -40,6 +40,10 @@ export class EntityManagerClient implements EntityManagerService {
   private readonly chainId: number
   private readonly contractAddress: string
   private readonly endpoint: string
+  private readonly apiKey?: string
+  private readonly apiSecret?: string
+  private readonly bearerToken?: string
+  private readonly appName?: string
 
   constructor(config_: EntityManagerConfig) {
     const config = mergeConfigWithDefaults(
@@ -51,6 +55,10 @@ export class EntityManagerClient implements EntityManagerService {
     this.contractAddress = config.contractAddress
     this.logger = config.logger.createPrefixedLogger('[entity-manager]')
     this.endpoint = config.endpoint
+    this.apiKey = config.apiKey
+    this.apiSecret = config.apiSecret
+    this.bearerToken = config.bearerToken
+    this.appName = config.appName
   }
 
   /**
@@ -87,13 +95,28 @@ export class EntityManagerClient implements EntityManagerService {
     const [senderAddress] = await this.audiusWalletClient.getAddresses()
     const signature = await this.audiusWalletClient.signTypedData(typedData)
 
-    const url = `${this.endpoint}/relay`
+    const params = new URLSearchParams()
+    if (this.apiKey) params.set('api_key', this.apiKey)
+    if (this.appName) params.set('app_name', this.appName)
+    const qs = params.toString()
+    const url = `${this.endpoint}/relay${qs ? `?${qs}` : ''}`
     this.logger.info(`Making relay request to ${url}`)
+
+    const headers = new Headers({
+      'Content-Type': 'application/json'
+    })
+
+    // Add auth header for API identification and rate limiting
+    if (this.bearerToken) {
+      headers.set('Authorization', `Bearer ${this.bearerToken}`)
+    } else if (this.apiKey && this.apiSecret) {
+      const credentials = btoa(`${this.apiKey}:${this.apiSecret}`)
+      headers.set('Authorization', `Basic ${credentials}`)
+    }
+
     const response = await fetch(url, {
       method: 'POST',
-      headers: new Headers({
-        'Content-Type': 'application/json'
-      }),
+      headers,
       body: JSON.stringify({
         contractAddress: this.contractAddress,
         contractRegistryKey: 'EntityManager',

package/src/sdk/services/EntityManager/types.ts

@@ -26,6 +26,14 @@ export type EntityManagerConfigInternal = {
    * The endpoint to use for relays
    */
   endpoint: string
+  /** API key for relay calls */
+  apiKey?: string
+  /** API secret for relay calls */
+  apiSecret?: string
+  /** Bearer token for relay calls */
+  bearerToken?: string
+  /** App name for relay calls */
+  appName?: string
 }
 export type EntityManagerConfig = Partial<EntityManagerConfigInternal> & {
   audiusWalletClient: AudiusWalletClient

package/src/sdk/services/Solana/programs/ClaimableTokensClient/ClaimableTokensClient.ts

@@ -182,6 +182,51 @@ export class ClaimableTokensClient {
     }
   }
 
+  /**
+   * Returns a create-user-bank instruction if the user bank does not yet exist,
+   * or null if it already does.  Does NOT send a transaction — the caller is
+   * expected to include the instruction in its own transaction.
+   */
+  async createUserBankIfNeededInstruction(
+    params: GetOrCreateUserBankRequest
+  ): Promise<{
+    userBank: PublicKey
+    instruction: ReturnType<
+      typeof ClaimableTokensProgram.createAccountInstruction
+    > | null
+  }> {
+    const args = await parseParams(
+      'createUserBankIfNeededInstruction',
+      GetOrCreateUserBankSchema
+    )(params)
+    const {
+      ethWallet = await this.getDefaultWalletAddress(),
+      feePayer: feePayerOverride
+    } = args
+    const mint = parseMint(args.mint, this.preconfiguredMints)
+    const feePayer = feePayerOverride ?? (await this.client.getFeePayer())
+    const userBank = await this.deriveUserBank(args)
+
+    const userBankAccount =
+      await this.client.connection.getAccountInfo(userBank)
+    if (!userBankAccount) {
+      this.logger.debug(
+        `User bank ${userBank} does not exist. Returning create instruction.`
+      )
+      const instruction = ClaimableTokensProgram.createAccountInstruction({
+        ethAddress: ethWallet,
+        payer: feePayer,
+        mint,
+        authority: this.deriveAuthority(mint),
+        userBank,
+        programId: this.programId
+      })
+      return { userBank, instruction }
+    }
+    this.logger.debug(`User bank ${userBank} already exists.`)
+    return { userBank, instruction: null }
+  }
+
   /**
    * Creates a claimable tokens program transfer instruction using configured
    * program ID, mint addresses, derived nonce, and derived authorities.
@@ -230,7 +275,8 @@ export class ClaimableTokensClient {
       destination,
       amount,
       mint: mintOrToken,
-      instructionIndex
+      instructionIndex,
+      nonce: nonceOverride
     } = await parseParams(
       'createTransferSecpInstruction',
       CreateSecpSchema
@@ -239,17 +285,23 @@ export class ClaimableTokensClient {
     const mint = parseMint(mintOrToken, this.preconfiguredMints)
 
     let nonce = BigInt(0)
-    const nonceKey = ClaimableTokensProgram.deriveNonce({
-      ethAddress: ethWallet,
-      authority: this.deriveAuthority(mint),
-      programId: this.programId
-    })
-    const nonceAccount = await this.client.connection.getAccountInfo(nonceKey)
-    const encodedNonceData = nonceAccount?.data
-    if (encodedNonceData) {
-      const nonceData =
-        ClaimableTokensProgram.layouts.nonceAccountData.decode(encodedNonceData)
-      nonce = nonceData.nonce
+    if (nonceOverride != null) {
+      nonce = nonceOverride
+    } else {
+      const nonceKey = ClaimableTokensProgram.deriveNonce({
+        ethAddress: ethWallet,
+        authority: this.deriveAuthority(mint),
+        programId: this.programId
+      })
+      const nonceAccount = await this.client.connection.getAccountInfo(nonceKey)
+      const encodedNonceData = nonceAccount?.data
+      if (encodedNonceData) {
+        const nonceData =
+          ClaimableTokensProgram.layouts.nonceAccountData.decode(
+            encodedNonceData
+          )
+        nonce = nonceData.nonce
+      }
     }
     const data = ClaimableTokensProgram.createSignedTransferInstructionData({
       destination,
@@ -268,6 +320,34 @@ export class ClaimableTokensClient {
     })
   }
 
+  /**
+   * Reads the current on-chain nonce for a user's claimable tokens account.
+   * Useful for callers that need to know the nonce before/after a transaction
+   * so they can pass it explicitly to subsequent {@link createTransferSecpInstruction} calls.
+   */
+  async getNonce({
+    ethWallet,
+    mint: mintOrToken
+  }: {
+    ethWallet: string
+    mint: PublicKey | TokenName
+  }): Promise<bigint> {
+    const mint = parseMint(mintOrToken, this.preconfiguredMints)
+    const nonceKey = ClaimableTokensProgram.deriveNonce({
+      ethAddress: ethWallet,
+      authority: this.deriveAuthority(mint),
+      programId: this.programId
+    })
+    const nonceAccount = await this.client.connection.getAccountInfo(nonceKey)
+    const encodedNonceData = nonceAccount?.data
+    if (encodedNonceData) {
+      const nonceData =
+        ClaimableTokensProgram.layouts.nonceAccountData.decode(encodedNonceData)
+      return nonceData.nonce
+    }
+    return BigInt(0)
+  }
+
   /**
    * Derives the user bank of a user from their Ethereum wallet and the token mint.
    *

package/src/sdk/services/Solana/programs/ClaimableTokensClient/types.ts

@@ -76,7 +76,11 @@ export const CreateSecpSchema = z
     /** The name of the token mint. */
     mint: MintSchema,
     /** The index of this instruction within the transaction. */
-    instructionIndex: z.number().optional()
+    instructionIndex: z.number().optional(),
+    /** Optional nonce override. When provided, skips the on-chain nonce lookup.
+     *  Useful when the caller knows the current nonce (e.g. after a prior transfer
+     *  that incremented it) and wants to avoid stale RPC reads. */
+    nonce: z.bigint().optional()
   })
   .strict()
 

package/src/sdk/services/Storage/Storage.ts

@@ -62,7 +62,18 @@ export class Storage implements StorageService {
                 reject(new Error('No node available'))
                 return
               }
-              upload = new tus.Upload(file as File, {
+              // In Node, tus-js-client accepts Buffer or fs.ReadStream as the
+              // source. When the caller passes a NodeFile wrapper
+              // (`{ buffer, name, type }`) — which is what the zod
+              // CrossPlatformFile schema validates in Node — unwrap it so the
+              // underlying Buffer reaches tus instead of the plain object.
+              const tusSource =
+                (file as any) &&
+                typeof Buffer !== 'undefined' &&
+                Buffer.isBuffer((file as any).buffer)
+                  ? (file as any).buffer
+                  : file
+              upload = new tus.Upload(tusSource as File, {
                 endpoint: `${selectedNode}/files/`,
                 retryDelays: [0, 3000, 5000, 10000, 20000],
                 chunkSize: 100_000_000, // 100MB

package/src/sdk/solanaWallet/SolanaWallet.ts

@@ -0,0 +1,61 @@
+import bs58 from 'bs58'
+
+export type SolanaWalletCredential = {
+  publicKey: string
+  message: string
+  signature: string
+}
+
+/**
+ * Minimal interface for a Solana wallet provider (Phantom, Solflare, etc.).
+ * Apps pass their connected wallet to `SolanaWallet.auth()`.
+ */
+export type SolanaWalletProvider = {
+  connect(): Promise<{ publicKey: { toString(): string } }>
+  signMessage(
+    message: Uint8Array,
+    encoding: string
+  ): Promise<{ signature: Uint8Array }>
+}
+
+export function createSolanaWalletSignatureMessage() {
+  const timestamp = Date.now()
+  const message = `audius:solana-wallet:${timestamp}`
+  const messageBytes = new TextEncoder().encode(message)
+  return { message, messageBytes, timestamp }
+}
+
+export class SolanaWallet {
+  private credential: SolanaWalletCredential | null = null
+
+  async auth(provider: SolanaWalletProvider) {
+    const { publicKey } = await provider.connect()
+    const { message, messageBytes } = createSolanaWalletSignatureMessage()
+    const { signature: sigBytes } = await provider.signMessage(
+      messageBytes,
+      'utf8'
+    )
+    this.credential = {
+      publicKey: publicKey.toString(),
+      message,
+      signature: bs58.encode(sigBytes)
+    }
+    return { publicKey: this.credential.publicKey }
+  }
+
+  setCredential(credential: SolanaWalletCredential) {
+    this.credential = credential
+  }
+
+  clearCredential() {
+    this.credential = null
+  }
+
+  getCredential(): SolanaWalletCredential | null {
+    return this.credential
+  }
+
+  isAuthenticated(): boolean {
+    return this.credential !== null
+  }
+}

package/src/sdk/solanaWallet/index.ts

@@ -0,0 +1,8 @@
+export {
+  SolanaWallet,
+  createSolanaWalletSignatureMessage
+} from './SolanaWallet'
+export type {
+  SolanaWalletCredential,
+  SolanaWalletProvider
+} from './SolanaWallet'

package/src/sdk/utils/mergeConfigs.ts

@@ -1,15 +1,59 @@
-import mergeWith from 'lodash/mergeWith'
+/**
+ * Plain objects only (Object.prototype or null proto). Class instances (Logger, etc.)
+ * are not plain and must not be structuredClone'd or deep-merged (would strip prototypes).
+ */
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  if (value === null || typeof value !== 'object') return false
+  if (Array.isArray(value)) return false
+  const proto = Object.getPrototypeOf(value)
+  return proto === null || proto === Object.prototype
+}
 
 /**
- * Gets the config with any undefined properties replaced by the defaults
- * @param config the config
- * @param defaults the defaults
- * @returns the merged config with defaults
+ * Deep-clone plain objects and arrays for immutable defaults. Keeps class instances
+ * by reference so methods like Logger#createPrefixedLogger remain.
  */
-export const mergeConfigWithDefaults = <T, K>(config: T, defaults: K) =>
-  mergeWith({}, defaults, config, (_a, b) => {
-    if (Array.isArray(b)) {
-      return b
+function cloneConfigDefaults(value: unknown): unknown {
+  if (value === null || typeof value !== 'object') return value
+  if (Array.isArray(value)) {
+    return value.map((item) => cloneConfigDefaults(item))
+  }
+  if (!isPlainObject(value)) {
+    return value
+  }
+  const out: Record<string, unknown> = {}
+  for (const k of Object.keys(value)) {
+    out[k] = cloneConfigDefaults(
+      (value as Record<string, unknown>)[k]
+    ) as unknown
+  }
+  return out
+}
+
+function mergeRec(
+  target: Record<string, unknown>,
+  source: Record<string, unknown>
+): Record<string, unknown> {
+  const result: Record<string, unknown> = { ...target }
+  for (const key of Object.keys(source)) {
+    const sv = source[key]
+    const tv = result[key]
+    if (Array.isArray(sv)) {
+      result[key] = sv
+    } else if (isPlainObject(sv) && isPlainObject(tv)) {
+      result[key] = mergeRec(tv, sv)
+    } else {
+      result[key] = sv
     }
-    return undefined
-  })
+  }
+  return result
+}
+
+/**
+ * Merges `config` over `defaults`. Arrays on `config` replace entirely (lodash mergeWith behavior).
+ * Only plain objects are deep-merged; class instances are replaced as a whole.
+ */
+export const mergeConfigWithDefaults = <T, K>(config: T, defaults: K) => {
+  const base = cloneConfigDefaults(defaults) as Record<string, unknown>
+  return mergeRec(base, config as Record<string, unknown>) as T & K
+}

package/src/sdk/utils/objectUtils.ts

@@ -0,0 +1,30 @@
+/**
+ * Small helpers replacing lodash for tree-shaking / fewer deps / Node ESM interop.
+ */
+
+/** Picks only keys present on `obj` (like lodash `pick`). */
+export function pick<T extends Record<string, unknown>>(
+  obj: T,
+  keys: readonly string[]
+): Record<string, unknown> {
+  const out: Record<string, unknown> = {}
+  for (const k of keys) {
+    if (Object.prototype.hasOwnProperty.call(obj, k)) {
+      out[k] = obj[k]
+    }
+  }
+  return out
+}
+
+/** Deduplicates by `iterateeKey` (first wins; like lodash `uniqBy`). */
+export function uniqBy<T>(arr: readonly T[], iterateeKey: keyof T): T[] {
+  const seen = new Set<unknown>()
+  const out: T[] = []
+  for (const item of arr) {
+    const v = item[iterateeKey]
+    if (seen.has(v)) continue
+    seen.add(v)
+    out.push(item)
+  }
+  return out
+}