refactor BotApi to adhere to Effect's best practices

Author: evermake

README.md

@@ -1,3 +1,9 @@
-Effectful library to interact with Telegram Bot API.
+Effectful library for crafting Telegram bots.
 
-> ⚠️ Work in progress.
+> [!WARNING]
+> Work in progress.
+
+## Features
+
+- Effectful and typesafe API.
+- Up-to-date and documented Bot API methods and types.

package.json

@@ -5,6 +5,7 @@
   "private": false,
   "scripts": {
     "gen": "bun run scripts/gen-bot-api.ts",
+    "typecheck": "tsc",
     "lint": "eslint .",
     "lint:fix": "eslint . --fix"
   },

scripts/gen-bot-api.ts

@@ -5,9 +5,9 @@ import { Project, Writers } from 'ts-morph'
 
 async function main() {
   const proj = new Project()
-  genTypes(proj.createSourceFile('./src/bot-api/internal/types.gen.ts', {}, { overwrite: true }))
-  genMethods(proj.createSourceFile('./src/bot-api/internal/methods.gen.ts', {}, { overwrite: true }))
-  genBotApi(proj.createSourceFile('./src/bot-api/internal/botApi.gen.ts', {}, { overwrite: true }))
+  genTypes(proj.createSourceFile('./src/internal/botApiTypes.gen.ts', {}, { overwrite: true }))
+  genMethods(proj.createSourceFile('./src/internal/botApiMethods.gen.ts', {}, { overwrite: true }))
+  genBotApiShape(proj.createSourceFile('./src/internal/botApiShape.gen.ts', {}, { overwrite: true }))
   await proj.save()
 }
 
@@ -49,12 +49,12 @@ function genMethods(f: SourceFile): void {
     inputFile: 'InputFile',
   }
   f.addImportDeclaration({
-    moduleSpecifier: './types.gen.ts',
+    moduleSpecifier: './botApiTypes.gen.ts',
     isTypeOnly: true,
     namespaceImport: 'Types',
   })
   f.addImportDeclaration({
-    moduleSpecifier: '../InputFile.ts',
+    moduleSpecifier: './inputFile.ts',
     isTypeOnly: true,
     namedImports: ['InputFile'],
   })
@@ -93,7 +93,7 @@ function genMethods(f: SourceFile): void {
   }
 }
 
-function genBotApi(f: SourceFile): void {
+function genBotApiShape(f: SourceFile): void {
   f.addImportDeclarations([
     {
       isTypeOnly: true,
@@ -104,7 +104,7 @@ function genBotApi(f: SourceFile): void {
   f.addInterface({
     isExported: true,
     isDefaultExport: false,
-    name: 'BotApi',
+    name: 'BotApiShape',
     properties: Object
       .values(methods)
       .map(({ name, description }) => ({

src/BotApi.ts

@@ -0,0 +1,12 @@
+import type { BotApiShape } from './internal/botApiShape.gen'
+import * as Context from 'effect/Context'
+import * as Layer from 'effect/Layer'
+import * as internal from './internal/botApi'
+
+export class BotApi extends Context.Tag('@grom.js/effectg/BotApi')<
+  BotApi,
+  BotApiShape
+>() {}
+
+export const make = internal.make
+export const layer = Layer.effect(BotApi, make)

src/BotApiError.ts

@@ -0,0 +1,15 @@
+import type * as Types from './internal/botApiTypes.gen'
+import * as Data from 'effect/Data'
+
+/**
+ * Error returned from the Bot API server in case of unsuccessful method call.
+ */
+export class BotApiError extends Data.TaggedError('@grom.js/effectg/BotApiError')<{
+  code: number
+  description: string
+  parameters?: Types.ResponseParameters
+}> {
+  override get message() {
+    return `(${this.code}) ${this.description}`
+  }
+}

src/BotApiTransport.ts

@@ -0,0 +1,48 @@
+import type * as Effect from 'effect/Effect'
+import type { BotApiTransportError } from './BotApiTransportError'
+import type * as Types from './internal/botApiTypes.gen'
+import { Layer } from 'effect'
+import * as Context from 'effect/Context'
+import * as internal from './internal/botApiTransport'
+
+export class BotApiTransport extends Context.Tag('@grom.js/effectg/BotApiTransport')<
+  BotApiTransport,
+  {
+    sendRequest: (
+      method: string,
+      params: unknown,
+    ) => Effect.Effect<BotApiResponse, BotApiTransportError>
+  }
+>() {
+}
+
+/**
+ * @see https://core.telegram.org/bots/api#making-requests
+ */
+export type BotApiResponse
+  = {
+    ok: true
+    result: unknown
+    description?: string
+  } | {
+    ok: false
+    error_code: number
+    description: string
+    parameters?: Types.ResponseParameters
+  }
+
+export const makeWith = internal.makeWith
+
+export const layerProd = (token: string) => Layer.effect(
+  BotApiTransport,
+  makeWith({
+    makeUrl: method => new URL(`https://api.telegram.org/bot${token}/${method}`),
+  }),
+)
+
+export const layerTest = (token: string) => Layer.effect(
+  BotApiTransport,
+  makeWith({
+    makeUrl: method => new URL(`https://api.telegram.org/bot${token}/test/${method}`),
+  }),
+)

src/BotApiTransportError.ts

@@ -0,0 +1,8 @@
+import * as Data from 'effect/Data'
+
+/**
+ * Error caused by the transport when accessing Bot API.
+ */
+export class BotApiTransportError extends Data.TaggedError('@grom.js/effectg/BotApiTransportError')<{
+  cause: unknown
+}> {}