V2

.changeset/README.md

@@ -0,0 +1,8 @@
+# Changesets
+
+Hello and welcome! This folder has been automatically generated by `@changesets/cli`, a build tool that works
+with multi-package repos, or single-package repos to help you version and publish your code. You can
+find the full documentation for it [in our repository](https://github.com/changesets/changesets)
+
+We have a quick list of common questions to get you started engaging with this project in
+[our documentation](https://github.com/changesets/changesets/blob/main/docs/common-questions.md)

.changeset/config.json

@@ -0,0 +1,18 @@
+{
+  "$schema": "https://unpkg.com/@changesets/config@2.3.0/schema.json",
+  "changelog": [
+    "@changesets/changelog-github",
+    {
+      "repo": "quran/api-js"
+    }
+  ],
+  "baseBranch": "main",
+  "commit": false,
+  "fixed": [],
+  "linked": [],
+  "access": "public",
+  "updateInternalDependencies": "patch",
+  "ignore": [
+    "@quranjs/docs"
+  ]
+}

.changeset/late-parks-return.md

@@ -0,0 +1,5 @@
+---
+"@quranjs/api": major
+---
+
+Migrate to the new quran.foundation API

.cursor/rules/clean-code.mdc

@@ -0,0 +1,55 @@
+---
+description: Guidelines for writing clean, maintainable, and human-readable code. Apply these rules when writing or reviewing code to ensure consistency and quality.
+globs: 
+alwaysApply: true
+---
+
+# Clean Code Guidelines
+
+## Constants Over Magic Numbers
+
+- Replace hard-coded values with named constants
+- Use descriptive constant names that explain the value's purpose
+- Keep constants at the top of the file or in a dedicated constants file
+
+## Meaningful Names
+
+- Variables, functions, and classes should reveal their purpose
+- Names should explain why something exists and how it's used
+- Avoid abbreviations unless they're universally understood
+
+## Smart Comments
+
+- Don't comment on what the code does - make the code self-documenting
+- Use comments to explain why something is done a certain way
+- Document APIs, complex algorithms, and non-obvious side effects
+
+## Single Responsibility
+
+- Each function should do exactly one thing
+- Functions should be small and focused
+- If a function needs a comment to explain what it does, it should be split
+
+## DRY (Don't Repeat Yourself)
+
+- Extract repeated code into reusable functions
+- Share common logic through proper abstraction
+- Maintain single sources of truth
+
+## Clean Structure
+
+- Keep related code together
+- Organize code in a logical hierarchy
+- Use consistent file and folder naming conventions
+
+## Encapsulation
+
+- Hide implementation details
+- Expose clear interfaces
+- Move nested conditionals into well-named functions
+
+## Code Quality Maintenance
+
+- Refactor continuously
+- Fix technical debt early
+- Leave code cleaner than you found it

.cursor/rules/general.mdc

@@ -0,0 +1,73 @@
+---
+description:
+globs:
+alwaysApply: true
+---
+
+# Overview
+
+You are an expert in TypeScript library development with excellent taste in API design.
+
+- Follow the user's requirements carefully & to the letter.
+- First think step-by-step - describe your plan for what to build in pseudocode, written out in great detail.
+
+## Tech Stack
+
+You're working in a monorepo using:
+
+- TypeScript
+- Pnpm
+- Vitest
+
+## Core Principles
+
+- Write straightforward, readable, and maintainable code. Use explicit types on exported functions.
+- Use strong typing, avoid 'any'.
+- Restate what the objective is of what you are being asked to change clearly in a short summary.
+- Do not use any third party library. The library must confirm to [Standard Schema](mdc:https:/standardschema.dev) and not be tied to any one schema validation library.
+- Reason about the API design before implementing changes. Is it possible to achieve strong and generic typing for your chosen API? If not, reconsider.
+- Create clearly documented changesets for your introduced changes using `pnpm changeset`.
+
+## Coding Standards
+
+### Naming Conventions
+
+- Variables, functions, methods: camelCase
+- Files, directories: kebab-case
+- Constants, env variables: UPPERCASE
+
+### Functions
+
+- Use descriptive names: verbs & nouns (e.g., getUserData)
+- Prefer the `function` keyword over arrow functions where their differences doesn't matter.
+- Document with JSDoc annotations
+
+### Types and Interfaces
+
+- Prefer custom interfaces over inline types
+- Use 'readonly' for immutable properties
+- If an import is only used as a type in the file, use 'import type' instead of 'import'
+
+### Validating changes
+
+- Always validate your changes confirm to the project lint configuration by running `pnpm lint`.
+- Write tests for changes and validate they pass using `pnpm test`.
+
+## Code Review Checklist
+
+- Ensure proper typing
+- Check for code duplication
+- Verify error handling
+- Confirm test coverage
+- Review naming conventions
+- Assess overall code structure and readability
+
+## Documentation
+
+- Use the active voice
+- Use the present tense
+- Write in a clear and concise manner
+- Present information in a logical order
+- Use lists and tables when appropriate
+- When writing JSDocs, only use TypeDoc compatible tags.
+- Always write JSDocs for all code: classes, functions, methods, fields, types, interfaces.

.github/setup/action.yml

@@ -0,0 +1,17 @@
+name: "Setup and install"
+description: "Common setup steps for Actions"
+
+runs:
+  using: composite
+  steps:
+    - uses: pnpm/action-setup@v4
+    - uses: actions/setup-node@v4
+      with:
+        node-version-file: ".nvmrc"
+        cache: "pnpm"
+
+    - shell: bash
+      run: pnpm add -g turbo
+
+    - shell: bash
+      run: pnpm install

.github/workflows/main.yml

@@ -1,71 +1,69 @@
 name: CI
 
-on: [push]
+on:
+  pull_request:
+    branches: ["*"]
+  push:
+    branches: ["main"]
+  merge_group:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: ${{ github.ref != 'refs/heads/main' }}
 
 env:
+  FORCE_COLOR: 3
   HUSKY: 0
 
 jobs:
   build:
-    if: github.repository == 'quran/api-js' && (github.ref == 'refs/heads/master') && github.event_name != 'pull_request'
-    name: ⚒️ Build, lint, and test on Node ${{ matrix.node }} and ${{ matrix.os }}
-
+    name: ⚒️ Build
     runs-on: ubuntu-latest
-    strategy:
-      matrix:
-        node: ['18.x', '20.x']
-
     steps:
       - name: Checkout repo
         uses: actions/checkout@v4
+      - uses: ./.github/setup
+      - run: pnpm build --filter="./packages/*"
 
-      - name: Setup PNPM
-        uses: pnpm/action-setup@v4
-
-      - name: Install Node.js ${{ matrix.node }}
-        uses: actions/setup-node@v4
-        with:
-          node-version: ${{ matrix.node }}
-          cache: "pnpm"
-
-      - name: Install dependencies
-        shell: bash
-        run: pnpm install
-
-      - name: Lint
-        run: pnpm lint --quiet
-
-      - name: Test
-        run: pnpm test:coverage
-
-      - name: Build
-        run: pnpm build
+  lint:
+    name: ✨ Lint
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repo
+        uses: actions/checkout@v4
+      - uses: ./.github/setup
+      - run: pnpm lint --quiet
 
-  test-and-publish:
-    name: 🎉 Publish to NPM
-    needs: [build]
-    if: github.repository == 'quran/api-js' && (github.ref == 'refs/heads/master') && github.event_name != 'pull_request'
+  typecheck:
+    name: 🔍 Typecheck
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - name: Checkout repo
+        uses: actions/checkout@v4
+      - uses: ./.github/setup
+      - run: pnpm typecheck
 
-      - name: Setup PNPM
-        uses: pnpm/action-setup@v4
+  test:
+    name: 🧪 Test
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repo
+        uses: actions/checkout@v4
+      - uses: ./.github/setup
+      - run: pnpm test
 
-      - uses: actions/setup-node@v4
+  size:
+    name: 📦 Size
+    runs-on: ubuntu-latest
+    env:
+      CI_JOB_NUMBER: 1
+    steps:
+      - name: Checkout repo
+        uses: actions/checkout@v4
+      - uses: ./.github/setup
+      - uses: andresz1/size-limit-action@v1.8.0
         with:
-          node-version: 20
-          registry-url: https://registry.npmjs.org/
-          cache: "pnpm"
-
-      - name: Install dependencies
-        shell: bash
-        run: pnpm install
-
-      - name: Build
-        run: pnpm build
-
-      - run: npx semantic-release@17
-        env:
-          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
-          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          directory: packages/api/
+          skip_step: install
+          package_manager: pnpm
+          github_token: ${{ secrets.GITHUB_TOKEN }}