@grom.js/effect-tg 0.8.0 → 0.10.0

package/src/BotApi.ts

@@ -1,35 +1,54 @@
+import type * as Config from 'effect/Config'
+import type * as ConfigError from 'effect/ConfigError'
 import type * as BotApiError from './BotApiError.ts'
-import type { MethodParams, MethodResults } from './internal/botApiMethods.gen.ts'
-import type { BotApiShape } from './internal/botApiShape.gen.ts'
-import type * as Types from './internal/botApiTypes.gen.ts'
+import type {
+  MethodParams,
+  MethodResults,
+  BotApi as Service,
+  Types,
+} from './internal/botApi.gen.ts'
+import * as HttpClient from '@effect/platform/HttpClient'
 import * as Context from 'effect/Context'
 import * as Effect from 'effect/Effect'
+import * as Function from 'effect/Function'
 import * as Layer from 'effect/Layer'
+import * as Redacted from 'effect/Redacted'
 import * as BotApiTransport from './BotApiTransport.ts'
+import * as BotApiUrl from './BotApiUrl.ts'
 import * as internal from './internal/botApi.ts'
 
-export type { MethodParams, MethodResults, Types }
+export type { MethodParams, MethodResults, Service, Types }
 
 export class BotApi extends Context.Tag('@grom.js/effect-tg/BotApi')<
   BotApi,
-  BotApi.Service
+  Service
 >() {}
 
-export declare namespace BotApi {
-  export type Service = BotApiShape
+export interface BotApiMethod<TMethod extends keyof MethodParams> {
+  (...args: MethodArgs<TMethod>): Effect.Effect<
+    MethodResults[TMethod],
+    BotApiError.BotApiError,
+    never
+  >
 }
 
-export interface Method<
-  M extends keyof MethodParams,
-  E = BotApiError.BotApiError | BotApiTransport.BotApiTransportError,
-  R = never,
-> {
-  (params: MethodParams[M]): Effect.Effect<MethodResults[M], E, R>
-}
+export const callMethod: <TMethod extends keyof MethodParams>(
+  method: TMethod,
+  ...args: MethodArgs<TMethod>
+) => Effect.Effect<
+  MethodResults[TMethod],
+  BotApiError.BotApiError,
+  BotApi
+> = (
+  method: string,
+  params: unknown = undefined,
+) => BotApi.pipe(
+  Effect.flatMap(api => (api as any)[method](params)),
+) as any
 
-export const make: (
-  transport: BotApiTransport.BotApiTransport.Service,
-) => BotApiShape = internal.make
+export const make: (args: {
+  transport: BotApiTransport.Service
+}) => Service = internal.make
 
 export const layer: Layer.Layer<
   BotApi,
@@ -37,19 +56,69 @@ export const layer: Layer.Layer<
   BotApiTransport.BotApiTransport
 > = Layer.effect(
   BotApi,
-  Effect.andThen(BotApiTransport.BotApiTransport, internal.make),
+  Effect.andThen(
+    BotApiTransport.BotApiTransport,
+    transport => internal.make({ transport }),
+  ),
 )
 
-export const callMethod: <M extends keyof MethodParams>(
-  method: M,
-  params: MethodParams[M],
-) => Effect.Effect<
-  MethodResults[M],
-  BotApiError.BotApiError | BotApiTransport.BotApiTransportError,
-  BotApi
-> = (
-  method: string,
-  params: unknown = undefined,
-) => BotApi.pipe(
-  Effect.flatMap((api: any) => api[method](params)),
-) as any
+type MethodArgs<TMethod extends keyof MethodParams> =
+  void extends MethodParams[TMethod]
+    ? [params?: MethodParams[TMethod]]
+    : [params: MethodParams[TMethod]]
+
+/**
+ * Constructs a `BotApi` layer from the given configuration.
+ */
+export const layerConfig = (options: {
+  /**
+   * Bot API token from [@BotFather](https://t.me/BotFather).
+   */
+  readonly token: Config.Config<Redacted.Redacted>
+
+  /**
+   * Target Bot API environment:
+   *
+   * - `prod` — production environment
+   * - `test` — [test environment](https://core.telegram.org/bots/features#dedicated-test-environment)
+   *
+   * @default 'prod'
+   */
+  readonly environment?: 'prod' | 'test'
+
+  /**
+   * A function to transform the underlying `BotApiTransport` before
+   * it's used to call Bot API methods.
+   *
+   * Useful for:
+   * - Adding custom middleware (logging, metrics, caching)
+   * - Adding custom retry logic or error handling
+   * - Integrating with monitoring or debugging tools
+   */
+  readonly transformTransport?: (transport: BotApiTransport.Service) => BotApiTransport.Service
+}): Layer.Layer<BotApi, ConfigError.ConfigError, HttpClient.HttpClient> => {
+  const {
+    token,
+    environment = 'prod',
+    transformTransport,
+  } = options
+  return Layer.provide(
+    layer,
+    Layer.effect(
+      BotApiTransport.BotApiTransport,
+      Effect.all([
+        HttpClient.HttpClient,
+        token.pipe(
+          Effect.map(token => (
+            environment === 'prod'
+              ? BotApiUrl.makeProd(Redacted.value(token))
+              : BotApiUrl.makeTest(Redacted.value(token))
+          )),
+        ),
+      ]).pipe(
+        Effect.map(([httpClient, botApiUrl]) => BotApiTransport.make({ httpClient, botApiUrl })),
+        Effect.map(transformTransport ?? Function.identity),
+      ),
+    ),
+  )
+}

package/src/BotApiError.ts

@@ -1,81 +1,127 @@
-import type * as Duration from 'effect/Duration'
-import type * as BotApi from './BotApi.ts'
+import type * as HttpBody from '@effect/platform/HttpBody'
+import type * as HttpClientError from '@effect/platform/HttpClientError'
+import type * as BotApiTransport from './BotApiTransport.ts'
 import * as Data from 'effect/Data'
+import * as Duration from 'effect/Duration'
+import * as Match from 'effect/Match'
+import * as Option from 'effect/Option'
+import * as Predicate from 'effect/Predicate'
+import * as Dialog from './Dialog.ts'
 import * as internal from './internal/botApiError.ts'
 
+export const TypeId = '@grom.js/effect-tg/BotApiError'
+
+export type TypeId = typeof TypeId
+
+export const isBotApiError = (u: unknown): u is BotApiError => Predicate.hasProperty(u, TypeId)
+
+export type BotApiError =
+  | TransportError
+  | MethodFailed
+  | GroupUpgraded
+  | RateLimited
+  | InternalServerError
+
 /**
- * Error returned from the Bot API server in case of unsuccessful method call.
+ * Error caused by the transport when accessing Bot API.
  */
-export class BotApiError extends Data.TaggedError('@grom.js/effect-tg/BotApiError')<{
-  code: number
-  description: string
-  parameters?: BotApi.Types.ResponseParameters
+export class TransportError extends Data.TaggedError('TransportError')<{
+  cause:
+    | HttpClientError.HttpClientError
+    | HttpBody.HttpBodyError
 }> {
+  readonly [TypeId]: TypeId = TypeId
+
   override get message() {
-    return `(${this.code}) ${this.description}`
+    return Match.value(this.cause).pipe(
+      Match.tagsExhaustive({
+        RequestError: e => e.message,
+        ResponseError: e => e.message,
+        HttpBodyError: e => Match.value(e.reason).pipe(
+          Match.tagsExhaustive({
+            SchemaError: e => e.error.message,
+            JsonError: e => `JsonError: ${e.error}`,
+          }),
+        ),
+      }),
+    )
   }
 }
 
-/**
- * Attempts to narrow a {@link BotApiError} to a more specific {@link KnownError}.
- *
- * **Warning!** Error types are detected based on the error code and message
- * returned from the Bot API, which are not guaranteed to be the same in
- * the future. If they change, this function may not determine error type
- * correctly.
- *
- * @see {@link https://github.com/tdlib/telegram-bot-api telegram-bot-api source code}
- */
-export const narrow: (error: BotApiError) => KnownError | BotApiError = internal.narrow
+export class MethodFailed extends Data.TaggedError('MethodFailed')<{
+  response: FailureResponse
+  possibleReason: MethodFailureReason
+}> {
+  readonly [TypeId]: TypeId = TypeId
+
+  override get message() {
+    return `(${this.response.error_code}) ${this.response.description}`
+  }
+}
 
-export type KnownError
-  = | TooManyRequests
-    | BotBlockedByUser
-    | MessageNotModified
-    | ReplyMarkupTooLong
-    | QueryIdInvalid
-    | MediaGroupedInvalid
+export class GroupUpgraded extends Data.TaggedError('GroupUpgraded')<{
+  response: FailureResponse
+  supergroup: Dialog.Supergroup
+}> {
+  readonly [TypeId]: TypeId = TypeId
 
-/**
- * Flood limit exceeded. Need to wait `retryAfter` before retrying.
- */
-export class TooManyRequests extends Data.TaggedError('@grom.js/effect-tg/BotApiError/TooManyRequests')<{
-  cause: BotApiError
+  override get message() {
+    return `Group has been upgraded to a supergroup with ID ${this.supergroup.id}.`
+  }
+}
+
+export class RateLimited extends Data.TaggedError('RateLimited')<{
+  response: FailureResponse
   retryAfter: Duration.Duration
-}> {}
+}> {
+  readonly [TypeId]: TypeId = TypeId
 
-/**
- * Bot was blocked by the user.
- */
-export class BotBlockedByUser extends Data.TaggedError('@grom.js/effect-tg/BotApiError/BotBlockedByUser')<{
-  cause: BotApiError
-}> {}
+  override get message() {
+    return `Flood limit exceeded. Should wait for ${Duration.format(this.retryAfter)} before retrying.`
+  }
+}
 
-/**
- * Message was not modified as its content and reply markup
- * are exactly the same as the current one.
- */
-export class MessageNotModified extends Data.TaggedError('@grom.js/effect-tg/BotApiError/MessageNotModified')<{
-  cause: BotApiError
-}> {}
+export class InternalServerError extends Data.TaggedError('InternalServerError')<{
+  response: FailureResponse
+}> {
+  readonly [TypeId]: TypeId = TypeId
+}
 
-/**
- * Message reply markup is too long.
- */
-export class ReplyMarkupTooLong extends Data.TaggedError('@grom.js/effect-tg/BotApiError/ReplyMarkupTooLong')<{
-  cause: BotApiError
-}> {}
+export const fromResponse = (response: FailureResponse): BotApiError => {
+  if (response.error_code === 429 && response.parameters?.retry_after != null) {
+    return new RateLimited({
+      response,
+      retryAfter: Duration.seconds(response.parameters.retry_after),
+    })
+  }
+  if (response.error_code === 400 && response.parameters?.migrate_to_chat_id != null) {
+    return new GroupUpgraded({
+      response,
+      supergroup: Dialog.supergroup(
+        Option.getOrThrow(
+          Dialog.decodePeerId('supergroup', response.parameters.migrate_to_chat_id),
+        ),
+      ),
+    })
+  }
+  if (response.error_code >= 500) {
+    return new InternalServerError({ response })
+  }
+  return new MethodFailed({
+    response,
+    possibleReason: internal.guessReason({
+      code: response.error_code,
+      description: response.description,
+    }),
+  })
+}
 
-/**
- * Query has expired, or ID is invalid.
- */
-export class QueryIdInvalid extends Data.TaggedError('@grom.js/effect-tg/BotApiError/QueryIdInvalid')<{
-  cause: BotApiError
-}> {}
+export type MethodFailureReason =
+  | 'Unknown'
+  | 'BotBlockedByUser'
+  | 'MessageNotModified'
+  | 'ReplyMarkupTooLong'
+  | 'QueryIdInvalid'
+  | 'MediaGroupedInvalid'
 
-/**
- * Invalid combination of media types in the media group.
- */
-export class MediaGroupedInvalid extends Data.TaggedError('@grom.js/effect-tg/BotApiError/MediaGroupedInvalid')<{
-  cause: BotApiError
-}> {}
+type FailureResponse = Extract<BotApiTransport.BotApiResponse, { ok: false }>

package/src/BotApiTransport.ts

@@ -1,7 +1,7 @@
-import type * as Types from './internal/botApiTypes.gen.ts'
+import type * as BotApi from './BotApi.ts'
+import type * as BotApiError from './BotApiError.ts'
 import * as HttpClient from '@effect/platform/HttpClient'
 import * as Context from 'effect/Context'
-import * as Data from 'effect/Data'
 import * as Effect from 'effect/Effect'
 import * as Layer from 'effect/Layer'
 import * as BotApiUrl from './BotApiUrl.ts'
@@ -9,23 +9,21 @@ import * as internal from './internal/botApiTransport.ts'
 
 export class BotApiTransport extends Context.Tag('@grom.js/effect-tg/BotApiTransport')<
   BotApiTransport,
-  BotApiTransport.Service
+  Service
 >() {}
 
-export declare namespace BotApiTransport {
-  export interface Service {
-    sendRequest: (
-      method: string,
-      params: unknown,
-    ) => Effect.Effect<BotApiResponse, BotApiTransportError>
-  }
+export interface Service {
+  sendRequest: (
+    method: string,
+    params: unknown,
+  ) => Effect.Effect<BotApiResponse, BotApiError.TransportError>
 }
 
 /**
  * @see https://core.telegram.org/bots/api#making-requests
  */
-export type BotApiResponse
-  = {
+export type BotApiResponse =
+  | {
     ok: true
     result: unknown
     description?: string
@@ -33,15 +31,13 @@ export type BotApiResponse
     ok: false
     error_code: number
     description: string
-    parameters?: Types.ResponseParameters
+    parameters?: BotApi.Types.ResponseParameters
   }
 
-/**
- * Error caused by the transport when accessing Bot API.
- */
-export class BotApiTransportError extends Data.TaggedError('@grom.js/effect-tg/BotApiTransport/BotApiTransportError')<{
-  cause: unknown
-}> {}
+export const make: (options: {
+  httpClient: HttpClient.HttpClient
+  botApiUrl: BotApiUrl.Service
+}) => Service = internal.make
 
 export const layer: Layer.Layer<
   BotApiTransport,
@@ -50,6 +46,8 @@ export const layer: Layer.Layer<
 > = Layer.effect(
   BotApiTransport,
   Effect.all([HttpClient.HttpClient, BotApiUrl.BotApiUrl]).pipe(
-    Effect.andThen(reqs => internal.make(...reqs)),
+    Effect.andThen(([httpClient, botApiUrl]) => (
+      internal.make({ httpClient, botApiUrl })),
+    ),
   ),
 )

package/src/BotApiUrl.ts

@@ -2,24 +2,22 @@ import * as Context from 'effect/Context'
 
 export class BotApiUrl extends Context.Tag('@grom.js/effect-tg/BotApiUrl')<
   BotApiUrl,
-  BotApiUrl.Service
+  Service
 >() {}
 
-export declare namespace BotApiUrl {
-  export interface Service {
-    toMethod: (method: string) => URL
-    toFile: (filePath: string) => URL
-  }
+export interface Service {
+  toMethod: (method: string) => URL
+  toFile: (filePath: string) => URL
 }
 
-export const makeProd = (token: string): BotApiUrl.Service => (
+export const makeProd = (token: string): Service => (
   {
     toMethod: (method: string) => new URL(`https://api.telegram.org/bot${token}/${method}`),
     toFile: (filePath: string) => new URL(`https://api.telegram.org/file/bot${token}/${filePath}`),
   }
 )
 
-export const makeTest = (token: string): BotApiUrl.Service => (
+export const makeTest = (token: string): Service => (
   {
     toMethod: (method: string) => new URL(`https://api.telegram.org/bot${token}/test/${method}`),
     // TODO: make sure this works in test environment

package/src/Content.ts

@@ -12,20 +12,20 @@ import * as Option from 'effect/Option'
  * @todo Invoices (fiat & stars)
  * @see {@link https://core.telegram.org/tdlib/docs/classtd_1_1td__api_1_1_input_message_content.html TDLib • td_api.InputMessageContent}
  */
-export type Content
-  = | Text
-    | Photo
-    | Audio
-    | Document
-    | Video
-    | Animation
-    | Voice
-    | VideoNote
-    | Location
-    | Venue
-    | Contact
-    | Dice
-    | Sticker
+export type Content =
+  | Text
+  | Photo
+  | Audio
+  | Document
+  | Video
+  | Animation
+  | Voice
+  | VideoNote
+  | Location
+  | Venue
+  | Contact
+  | Dice
+  | Sticker
 
 /**
  * Content of a text message.