@amirstack/chapar 0.1.0

package/LICENSE

@@ -0,0 +1,20 @@
+MIT License
+
+Copyright (c) 2025 Shopify Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1 @@
+# @amirstack/chapar

package/dist/chapar.d.ts

@@ -0,0 +1,13 @@
+import { type ChaparConfiguration } from './config';
+type SendParameters = {
+    content: {
+        text: string;
+    };
+};
+export declare class Chapar {
+    #private;
+    constructor(config?: ChaparConfiguration);
+    send(params: SendParameters): Promise<void>;
+}
+export {};
+//# sourceMappingURL=chapar.d.ts.map

package/dist/chapar.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chapar.d.ts","sourceRoot":"","sources":["../src/lib/chapar.ts"],"names":[],"mappings":"AAAA,OAAO,EAAgB,KAAK,mBAAmB,EAAE,MAAM,UAAU,CAAA;AAIjE,KAAK,cAAc,GAAG;IACpB,OAAO,EAAE;QACP,IAAI,EAAE,MAAM,CAAA;KACb,CAAA;CACF,CAAA;AAED,qBAAa,MAAM;;IAGjB,YAAY,MAAM,CAAC,EAAE,mBAAmB,EAEvC;IAoBK,IAAI,CAAC,MAAM,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CAGhD;CACF"}

package/dist/config.d.ts

@@ -0,0 +1,18 @@
+export type ChaparConfiguration = {
+    apiUrl?: string;
+    auth?: {
+        clientId?: string;
+        clientSecret?: string;
+    };
+};
+type DeepRequired<T> = T extends (...args: any[]) => any ? T : T extends object ? {
+    [K in keyof T]-?: DeepRequired<T[K]>;
+} : T;
+type ResolvedConfiguration = DeepRequired<ChaparConfiguration>;
+export declare class ChaparConfig {
+    #private;
+    constructor(config?: ChaparConfiguration);
+    resolve(): ResolvedConfiguration;
+}
+export {};
+//# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/lib/config.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,mBAAmB,GAAG;IAChC,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,IAAI,CAAC,EAAE;QACL,QAAQ,CAAC,EAAE,MAAM,CAAA;QACjB,YAAY,CAAC,EAAE,MAAM,CAAA;KACtB,CAAA;CACF,CAAA;AAED,KAAK,YAAY,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG,GACpD,CAAC,GACD,CAAC,SAAS,MAAM,GACd;KAAG,CAAC,IAAI,MAAM,CAAC,CAAC,CAAC,GAAG,YAAY,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;CAAE,GACxC,CAAC,CAAA;AAEP,KAAK,qBAAqB,GAAG,YAAY,CAAC,mBAAmB,CAAC,CAAA;AAE9D,qBAAa,YAAY;;IAGvB,YAAY,MAAM,CAAC,EAAE,mBAAmB,EAEvC;IA0BD,OAAO,IAAI,qBAAqB,CAoB/B;CACF"}

package/dist/errors.d.ts

@@ -0,0 +1,22 @@
+export declare class ChaparError extends Error {
+}
+export declare class ChaparAuthError extends ChaparError {
+}
+export declare class ChaparUnparsableError extends ChaparError {
+}
+export declare class ChaparServerError extends ChaparError {
+}
+export declare class ChaparSendError extends ChaparError {
+    readonly code: string;
+    readonly details: unknown;
+    constructor(error: {
+        code: string;
+        message: string;
+        details?: unknown;
+    });
+}
+export declare class ChaparUnhandledError extends ChaparError {
+}
+export declare class ChaparConfigResolvingFailure extends ChaparError {
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/lib/errors.ts"],"names":[],"mappings":"AAAA,qBAAa,WAAY,SAAQ,KAAK;CAAG;AACzC,qBAAa,eAAgB,SAAQ,WAAW;CAAG;AACnD,qBAAa,qBAAsB,SAAQ,WAAW;CAAG;AACzD,qBAAa,iBAAkB,SAAQ,WAAW;CAAG;AACrD,qBAAa,eAAgB,SAAQ,WAAW;IAC9C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;IAEzB,YAAY,KAAK,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,OAAO,CAAA;KAAE,EAItE;CACF;AACD,qBAAa,oBAAqB,SAAQ,WAAW;CAAG;AACxD,qBAAa,4BAA6B,SAAQ,WAAW;CAAG"}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { Chapar } from './chapar';
+export { ChaparConfig, type ChaparConfiguration } from './config';
+export { ChaparAuthError, ChaparConfigResolvingFailure, ChaparError, ChaparSendError, ChaparServerError, ChaparUnhandledError, ChaparUnparsableError, } from './errors';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/lib/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,UAAU,CAAA;AACjC,OAAO,EAAE,YAAY,EAAE,KAAK,mBAAmB,EAAE,MAAM,UAAU,CAAA;AACjE,OAAO,EACL,eAAe,EACf,4BAA4B,EAC5B,WAAW,EACX,eAAe,EACf,iBAAiB,EACjB,oBAAoB,EACpB,qBAAqB,GACtB,MAAM,UAAU,CAAA"}

package/dist/response.d.ts

@@ -0,0 +1,2 @@
+export declare function parseResponse(response: Response): Promise<unknown>;
+//# sourceMappingURL=response.d.ts.map

package/dist/response.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"response.d.ts","sourceRoot":"","sources":["../src/lib/response.ts"],"names":[],"mappings":"AA0DA,wBAAsB,aAAa,CAAC,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAAC,OAAO,CAAC,CAaxE"}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@amirstack/chapar",
+  "version": "0.1.0",
+  "description": "Client for sending messages through the Chapar API.",
+  "author": "Amir Ziaei <a@amirziaei.me> (https://amirziaei.me)",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/amir-ziaei/chapar",
+    "directory": "packages/client"
+  },
+  "homepage": "https://github.com/amir-ziaei/chapar/tree/main/packages/client#readme",
+  "files": [
+    "LICENSE",
+    "README.md",
+    "dist",
+    "src",
+    "!src/**/*.test.ts"
+  ],
+  "type": "module",
+  "exports": {
+    ".": "./src/lib/index.ts",
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "exports": {
+      ".": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "./package.json": "./package.json"
+    }
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "test": "vitest",
+    "lint": "oxlint",
+    "lint:fix": "oxlint --fix",
+    "fmt": "oxfmt --check",
+    "fmt:fix": "oxfmt",
+    "types": "tsc --noEmit",
+    "validate": "bun --parallel lint fmt types build",
+    "prepublishOnly": "bun run build"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "msw": "^2.14.6",
+    "vitest": "^4.1.10"
+  }
+}

package/src/lib/chapar.ts

@@ -0,0 +1,40 @@
+import { ChaparConfig, type ChaparConfiguration } from './config'
+import { ChaparUnhandledError } from './errors'
+import { parseResponse } from './response'
+
+type SendParameters = {
+  content: {
+    text: string
+  }
+}
+
+export class Chapar {
+  readonly #config: ChaparConfig
+
+  constructor(config?: ChaparConfiguration) {
+    this.#config = new ChaparConfig(config)
+  }
+
+  async #request(params: SendParameters): Promise<Response> {
+    const config = this.#config.resolve()
+    try {
+      return await fetch(config.apiUrl, {
+        method: 'POST',
+        headers: {
+          'CF-Access-Client-Id': config.auth.clientId,
+          'CF-Access-Client-Secret': config.auth.clientSecret,
+        },
+        body: JSON.stringify(params),
+      })
+    } catch (cause) {
+      throw new ChaparUnhandledError('The request could not be completed', {
+        cause,
+      })
+    }
+  }
+
+  async send(params: SendParameters): Promise<void> {
+    const response = await this.#request(params)
+    await parseResponse(response)
+  }
+}

package/src/lib/config.ts

@@ -0,0 +1,71 @@
+import { ChaparConfigResolvingFailure } from './errors'
+
+export type ChaparConfiguration = {
+  apiUrl?: string
+  auth?: {
+    clientId?: string
+    clientSecret?: string
+  }
+}
+
+type DeepRequired<T> = T extends (...args: any[]) => any
+  ? T
+  : T extends object
+    ? { [K in keyof T]-?: DeepRequired<T[K]> }
+    : T
+
+type ResolvedConfiguration = DeepRequired<ChaparConfiguration>
+
+export class ChaparConfig {
+  readonly #config?: ChaparConfiguration
+
+  constructor(config?: ChaparConfiguration) {
+    this.#config = config
+  }
+
+  #readEnv(key: string): string | undefined {
+    if (typeof process === 'undefined' || typeof process.env === 'undefined') {
+      return undefined
+    }
+    return process.env[key]
+  }
+
+  #resolveValue(
+    value: string | undefined,
+    envKey: string,
+    name: string,
+  ): string {
+    if (value) {
+      return value
+    }
+    const envValue = this.#readEnv(envKey)
+    if (envValue) {
+      return envValue
+    }
+    throw new ChaparConfigResolvingFailure(
+      `Missing required configuration: ${name}`,
+    )
+  }
+
+  resolve(): ResolvedConfiguration {
+    return {
+      apiUrl: this.#resolveValue(
+        this.#config?.apiUrl,
+        'CHAPAR_API_URL',
+        'apiUrl',
+      ),
+      auth: {
+        clientId: this.#resolveValue(
+          this.#config?.auth?.clientId,
+          'CHAPAR_AUTH_CLIENT_ID',
+          'auth.clientId',
+        ),
+        clientSecret: this.#resolveValue(
+          this.#config?.auth?.clientSecret,
+          'CHAPAR_AUTH_CLIENT_SECRET',
+          'auth.clientSecret',
+        ),
+      },
+    }
+  }
+}

package/src/lib/errors.ts

@@ -0,0 +1,16 @@
+export class ChaparError extends Error {}
+export class ChaparAuthError extends ChaparError {}
+export class ChaparUnparsableError extends ChaparError {}
+export class ChaparServerError extends ChaparError {}
+export class ChaparSendError extends ChaparError {
+  readonly code: string
+  readonly details: unknown
+
+  constructor(error: { code: string; message: string; details?: unknown }) {
+    super(error.message)
+    this.code = error.code
+    this.details = error.details
+  }
+}
+export class ChaparUnhandledError extends ChaparError {}
+export class ChaparConfigResolvingFailure extends ChaparError {}

package/src/lib/index.ts

@@ -0,0 +1,11 @@
+export { Chapar } from './chapar'
+export { ChaparConfig, type ChaparConfiguration } from './config'
+export {
+  ChaparAuthError,
+  ChaparConfigResolvingFailure,
+  ChaparError,
+  ChaparSendError,
+  ChaparServerError,
+  ChaparUnhandledError,
+  ChaparUnparsableError,
+} from './errors'

package/src/lib/response.ts

@@ -0,0 +1,72 @@
+import {
+  ChaparAuthError,
+  ChaparSendError,
+  ChaparServerError,
+  ChaparUnparsableError,
+} from './errors'
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === 'object' && value !== null
+
+type ParsedEnvelope =
+  | { ok: true; data: unknown }
+  | {
+      ok: false
+      error: { code: string; message: string; details: unknown }
+    }
+
+function parseEnvelope(data: unknown): ParsedEnvelope {
+  if (!isRecord(data) || typeof data.ok !== 'boolean') {
+    throw new ChaparUnparsableError()
+  }
+
+  if (data.ok) {
+    return { ok: true, data: data.data }
+  }
+
+  const { error } = data
+  if (
+    !isRecord(error) ||
+    typeof error.code !== 'string' ||
+    typeof error.message !== 'string'
+  ) {
+    throw new ChaparUnparsableError()
+  }
+
+  return {
+    ok: false,
+    error: {
+      code: error.code,
+      message: error.message,
+      details: error.details,
+    },
+  }
+}
+
+async function readJson(response: Response): Promise<unknown> {
+  if (response.headers.get('Content-Type') !== 'application/json') {
+    throw new ChaparUnparsableError()
+  }
+  try {
+    return await response.json()
+  } catch (cause) {
+    throw new ChaparUnparsableError('The response body was not valid JSON', {
+      cause,
+    })
+  }
+}
+
+export async function parseResponse(response: Response): Promise<unknown> {
+  if (response.status === 401 || response.status === 403) {
+    throw new ChaparAuthError()
+  }
+  if (response.status >= 500) {
+    throw new ChaparServerError()
+  }
+
+  const parsed = parseEnvelope(await readJson(response))
+  if (!parsed.ok) {
+    throw new ChaparSendError(parsed.error)
+  }
+  return parsed.data
+}