أتمتة طلبات التنفيذ القضائي السعودي عبر واجهة برمجة ناجز في TypeScript

npm init -y
npm install zod
npm install -D typescript @types/node tsx vitest

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "strict": true,
    "noUncheckedIndexedAccess": true,
    "exactOptionalPropertyTypes": true,
    "outDir": "dist"
  }
}

NAJIZ_BASE_URL=https://api.najiz.sa
NAJIZ_CLIENT_ID=your-client-id
NAJIZ_CLIENT_SECRET=your-client-secret
CREDITOR_NID=1234567890

// src/types.ts
import { z } from 'zod'
 
// أنواع السندات التنفيذية الثلاثة
export type JudicialJudgment = {
  kind: 'judicial_judgment'
  caseNumber: string
  courtCode: string
  executionCourseDate: string  // تاريخ ISO مثل "2026-07-15"
}
 
export type NotarizedNote = {
  kind: 'notarized_note'
  nafithInstrumentId: string   // صادر من منصة نافذ للتوثيق
  notarizationDate: string
}
 
export type CommercialPaper = {
  kind: 'commercial_paper'
  paperType: 'check' | 'bill_of_exchange'
  paperNumber: string
  bankCode: string
  dueDate: string
}
 
export type InstrumentKind = JudicialJudgment | NotarizedNote | CommercialPaper
 
// هوية المدين — فرد أو كيان تجاري
export const NidSchema = z
  .string()
  .regex(/^[12]\d{9}$/, 'رقم الهوية 10 أرقام يبدأ بـ 1 (سعودي) أو 2 (إقامة)')
 
export const CrSchema = z.string().regex(/^\d{10}$/, 'رقم السجل التجاري 10 أرقام')
 
export type IndividualDebtor = { type: 'individual'; nid: string; fullName: string }
export type CommercialDebtor = {
  type: 'commercial'
  crNumber: string
  entityName: string
  representativeNid: string
}
export type Debtor = IndividualDebtor | CommercialDebtor
 
// مبلغ التنفيذ — دائماً بالريال السعودي، لا بالهللة
// (على عكس Moyasar الذي يستخدم الهللة؛ راجع دليل بوابة الدفع)
export type EnforcementAmount = {
  principalSar: number    // قيمة الدين الأصلي
  courtFeesSar: number    // رسوم المحكمة القابلة للاسترداد
  legalCostsSar: number   // أتعاب المحامي / التوثيق القابلة للاسترداد
}
 
export function totalSar(a: EnforcementAmount): number {
  return a.principalSar + a.courtFeesSar + a.legalCostsSar
}
 
// آلة حالة دورة حياة الطلب
export type RequestStatus =
  | 'submitted'           // مُقدَّم، في انتظار الإسناد للمحكمة
  | 'under_review'        // القاضي يراجع صحة السند
  | 'notice_issued'       // تم إخطار المدين؛ نافذة الرد (5 أيام) مفتوحة
  | 'grace_period'        // مهلة ممنوحة من المحكمة للمدين
  | 'enforced'            // تم تنفيذ الحكم بالكامل
  | 'partially_enforced'  // استرداد جزئي (حجز الأصول، يوجد عجز)
  | 'rejected'            // السند غير صحيح أو خلل إجرائي
  | 'suspended'           // المدين دخل إجراءات الإفلاس
  | 'withdrawn'           // الدائن سحب الطلب
 
export const TERMINAL_STATUSES = new Set<RequestStatus>([
  'enforced',
  'partially_enforced',
  'rejected',
  'suspended',
  'withdrawn',
])

// src/port.ts
import type { InstrumentKind, EnforcementAmount, Debtor, RequestStatus } from './types.js'
 
export type CreditorInstrument = {
  instrumentId: string
  kind: InstrumentKind
  amount: EnforcementAmount
  issuedAt: string
  status: 'valid' | 'partially_used' | 'exhausted' | 'expired'
}
 
export type EnforcementRequestInput = {
  creditorNid: string
  instrument: InstrumentKind
  debtor: Debtor
  amount: EnforcementAmount
  sourceInvoiceRef: string   // رقم الفاتورة الداخلية للتتبع
}
 
export type SubmitResult = {
  requestId: string
  referenceNumber: string   // رقم المرجع الظاهر في المراسلات
  submittedAt: string
}
 
export type StatusResult = {
  requestId: string
  status: RequestStatus
  noticeIssuedAt: string | null
  gracePeriodExpiresAt: string | null
  lastUpdatedAt: string
}
 
export interface NajizEnforcementPort {
  queryCreditorInstruments(creditorNid: string): Promise<CreditorInstrument[]>
  submitRequest(input: EnforcementRequestInput): Promise<SubmitResult>
  uploadAttachment(
    requestId: string,
    file: Buffer,
    filename: string,
  ): Promise<{ attachmentId: string }>
  getStatus(requestId: string): Promise<StatusResult>
}

// src/client.ts
import { createHash } from 'crypto'
import { NidSchema, CrSchema } from './types.js'
import type {
  NajizEnforcementPort,
  CreditorInstrument,
  EnforcementRequestInput,
  SubmitResult,
  StatusResult,
} from './port.js'
 
export class NajizHttpClient implements NajizEnforcementPort {
  private cached: { value: string; expiresAt: number } | null = null
 
  constructor(
    private readonly baseUrl: string,
    private readonly clientId: string,
    private readonly clientSecret: string,
  ) {}
 
  private async token(): Promise<string> {
    if (this.cached && Date.now() < this.cached.expiresAt - 30_000) {
      return this.cached.value
    }
    const res = await fetch(`${this.baseUrl}/oauth2/token`, {
      method: 'POST',
      headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
      body: new URLSearchParams({
        grant_type: 'client_credentials',
        client_id: this.clientId,
        client_secret: this.clientSecret,
        scope: 'enforcement:read enforcement:write',
      }),
    })
    if (!res.ok) throw new Error(`فشل في المصادقة: HTTP ${res.status}`)
    const body = (await res.json()) as { access_token: string; expires_in: number }
    this.cached = {
      value: body.access_token,
      expiresAt: Date.now() + body.expires_in * 1_000,
    }
    return this.cached.value
  }
 
  private async get<T>(path: string): Promise<T> {
    const res = await fetch(`${this.baseUrl}${path}`, {
      headers: {
        Authorization: `Bearer ${await this.token()}`,
        Accept: 'application/json',
      },
    })
    if (!res.ok) throw new Error(`GET ${path} → HTTP ${res.status}`)
    return res.json() as Promise<T>
  }
 
  private async post<T>(path: string, body: unknown): Promise<T> {
    const res = await fetch(`${this.baseUrl}${path}`, {
      method: 'POST',
      headers: {
        Authorization: `Bearer ${await this.token()}`,
        'Content-Type': 'application/json',
        Accept: 'application/json',
      },
      body: JSON.stringify(body),
    })
    if (!res.ok) throw new Error(`POST ${path} → HTTP ${res.status}`)
    return res.json() as Promise<T>
  }

  async queryCreditorInstruments(creditorNid: string): Promise<CreditorInstrument[]> {
    const body = await this.get<{ instruments: CreditorInstrument[] }>(
      `/v1/enforcement/instruments?creditorNid=${creditorNid}`,
    )
    return body.instruments
  }
 
  async submitRequest(input: EnforcementRequestInput): Promise<SubmitResult> {
    // التحقق من هوية المدين قبل الإرسال عبر الشبكة
    if (input.debtor.type === 'individual') {
      NidSchema.parse(input.debtor.nid)
    } else {
      CrSchema.parse(input.debtor.crNumber)
      NidSchema.parse(input.debtor.representativeNid)
    }
    return this.post<SubmitResult>('/v1/enforcement/requests', buildPayload(input))
  }

function buildPayload(input: EnforcementRequestInput) {
  const base = {
    creditorNid: input.creditorNid,
    sourceInvoiceRef: input.sourceInvoiceRef,
    amount: {
      principal: input.amount.principalSar,
      courtFees: input.amount.courtFeesSar,
      legalCosts: input.amount.legalCostsSar,
    },
    debtor:
      input.debtor.type === 'individual'
        ? { type: 'individual', nid: input.debtor.nid, name: input.debtor.fullName }
        : {
            type: 'commercial',
            crNumber: input.debtor.crNumber,
            name: input.debtor.entityName,
            representativeNid: input.debtor.representativeNid,
          },
  }
 
  switch (input.instrument.kind) {
    case 'judicial_judgment':
      return {
        ...base,
        instrumentType: 'judicial_judgment',
        caseNumber: input.instrument.caseNumber,
        courtCode: input.instrument.courtCode,
        executionCourseDate: input.instrument.executionCourseDate,
      }
    case 'notarized_note':
      return {
        ...base,
        instrumentType: 'notarized_note',
        nafithInstrumentId: input.instrument.nafithInstrumentId,
        notarizationDate: input.instrument.notarizationDate,
      }
    case 'commercial_paper':
      return {
        ...base,
        instrumentType: 'commercial_paper',
        paperType: input.instrument.paperType,
        paperNumber: input.instrument.paperNumber,
        bankCode: input.instrument.bankCode,
        dueDate: input.instrument.dueDate,
      }
  }
}

  async uploadAttachment(
    requestId: string,
    file: Buffer,
    filename: string,
  ): Promise<{ attachmentId: string }> {
    const form = new FormData()
    form.append('file', new Blob([file], { type: 'application/pdf' }), filename)
    form.append('requestId', requestId)
    form.append('contentHash', createHash('sha256').update(file).digest('hex'))
 
    const res = await fetch(`${this.baseUrl}/v1/enforcement/attachments`, {
      method: 'POST',
      headers: { Authorization: `Bearer ${await this.token()}` },
      body: form,
    })
    if (!res.ok) throw new Error(`فشل رفع المرفق: HTTP ${res.status}`)
    return res.json() as Promise<{ attachmentId: string }>
  }
 
  async getStatus(requestId: string): Promise<StatusResult> {
    return this.get<StatusResult>(`/v1/enforcement/requests/${requestId}/status`)
  }
}

// src/reconcile.ts
import { TERMINAL_STATUSES, type RequestStatus } from './types.js'
import type { NajizEnforcementPort, StatusResult } from './port.js'
 
export type OutstandingRow = {
  requestId: string
  status: RequestStatus
  noticeIssuedAt: string | null
}
 
export type ReconciliationResult = {
  requestId: string
  prevStatus: RequestStatus
  newStatus: RequestStatus
  daysSinceNotice: number | null
  needsEscalation: boolean       // notice_issued وتجاوز 5 أيام
  gracePeriodExpired: boolean    // grace_period وانتهت المهلة
}
 
export async function reconcileRequests(
  port: NajizEnforcementPort,
  rows: OutstandingRow[],
  asOf: Date,
): Promise<ReconciliationResult[]> {
  const pending = rows.filter((r) => !TERMINAL_STATUSES.has(r.status))
 
  return Promise.all(
    pending.map(async (row): Promise<ReconciliationResult> => {
      const current = await port.getStatus(row.requestId)
 
      const daysSinceNotice =
        row.noticeIssuedAt != null
          ? Math.floor(
              (asOf.getTime() - new Date(row.noticeIssuedAt).getTime()) / 86_400_000,
            )
          : null
 
      return {
        requestId: row.requestId,
        prevStatus: row.status,
        newStatus: current.status,
        daysSinceNotice,
        needsEscalation:
          current.status === 'notice_issued' && (daysSinceNotice ?? 0) > 5,
        gracePeriodExpired:
          current.status === 'grace_period' &&
          current.gracePeriodExpiresAt != null &&
          new Date(current.gracePeriodExpiresAt) < asOf,
      }
    }),
  )
}

// src/mock-port.ts
import { createHash } from 'crypto'
import { TERMINAL_STATUSES, type RequestStatus } from './types.js'
import type {
  NajizEnforcementPort,
  CreditorInstrument,
  EnforcementRequestInput,
  SubmitResult,
  StatusResult,
} from './port.js'
 
export class MockNajizPort implements NajizEnforcementPort {
  private readonly store = new Map<string, StatusResult>()
  private seq = 0
 
  async queryCreditorInstruments(
    _creditorNid: string,
  ): Promise<CreditorInstrument[]> {
    return []  // اسكن البيانات التجريبية في كل اختبار
  }
 
  async submitRequest(_input: EnforcementRequestInput): Promise<SubmitResult> {
    const id = `MOCK-${String(++this.seq).padStart(6, '0')}`
    this.store.set(id, {
      requestId: id,
      status: 'submitted',
      noticeIssuedAt: null,
      gracePeriodExpiresAt: null,
      lastUpdatedAt: new Date().toISOString(),
    })
    return {
      requestId: id,
      referenceNumber: `REF-${id}`,
      submittedAt: new Date().toISOString(),
    }
  }
 
  async uploadAttachment(
    _requestId: string,
    file: Buffer,
    _filename: string,
  ): Promise<{ attachmentId: string }> {
    return {
      attachmentId: `ATT-${createHash('sha256').update(file).digest('hex').slice(0, 12)}`,
    }
  }
 
  async getStatus(requestId: string): Promise<StatusResult> {
    const r = this.store.get(requestId)
    if (!r) throw new Error(`MockNajizPort: requestId غير معروف ${requestId}`)
    return r
  }
 
  /** مساعد الاختبار: نقل الطلب إلى حالة معينة */
  advance(
    requestId: string,
    status: RequestStatus,
    patch: Partial<
      Pick<StatusResult, 'noticeIssuedAt' | 'gracePeriodExpiresAt'>
    > = {},
  ): void {
    const prev = this.store.get(requestId)
    if (!prev) throw new Error(`MockNajizPort: requestId غير معروف ${requestId}`)
    this.store.set(requestId, {
      ...prev,
      status,
      lastUpdatedAt: new Date().toISOString(),
      ...patch,
    })
  }
}

// src/reconcile.test.ts
import { describe, it, expect } from 'vitest'
import { MockNajizPort } from './mock-port.js'
import { reconcileRequests } from './reconcile.js'
 
const SAMPLE_INPUT: import('./port.js').EnforcementRequestInput = {
  creditorNid: '1234567890',
  instrument: {
    kind: 'notarized_note',
    nafithInstrumentId: 'NF-2026-001',
    notarizationDate: '2026-08-01',
  },
  debtor: { type: 'individual', nid: '2345678901', fullName: 'اسم المدين' },
  amount: { principalSar: 50_000, courtFeesSar: 1_000, legalCostsSar: 500 },
  sourceInvoiceRef: 'INV-2026-0042',
}
 
describe('reconcileRequests', () => {
  it('يكشف notice_issued المتجاوز للـ5 أيام', async () => {
    const port = new MockNajizPort()
    const { requestId } = await port.submitRequest(SAMPLE_INPUT)
 
    const noticeIssuedAt = '2026-08-10T08:00:00.000Z'
    port.advance(requestId, 'notice_issued', { noticeIssuedAt })
 
    const results = await reconcileRequests(
      port,
      [{ requestId, status: 'notice_issued', noticeIssuedAt }],
      new Date('2026-08-16T08:00:00.000Z'),  // 6 أيام لاحقاً
    )
 
    expect(results[0]?.needsEscalation).toBe(true)
    expect(results[0]?.daysSinceNotice).toBe(6)
  })
 
  it('يتجاهل الطلبات في الحالات النهائية', async () => {
    const port = new MockNajizPort()
    const { requestId } = await port.submitRequest(SAMPLE_INPUT)
    port.advance(requestId, 'enforced')
 
    const results = await reconcileRequests(
      port,
      [{ requestId, status: 'enforced', noticeIssuedAt: null }],
      new Date('2026-08-17T00:00:00.000Z'),
    )
 
    expect(results).toHaveLength(0)
  })
 
  it('يكشف انتهاء مهلة المدين', async () => {
    const port = new MockNajizPort()
    const { requestId } = await port.submitRequest(SAMPLE_INPUT)
 
    port.advance(requestId, 'grace_period', {
      gracePeriodExpiresAt: '2026-08-14T00:00:00.000Z',
    })
 
    const results = await reconcileRequests(
      port,
      [{ requestId, status: 'grace_period', noticeIssuedAt: '2026-08-10T08:00:00.000Z' }],
      new Date('2026-08-15T00:00:00.000Z'),
    )
 
    expect(results[0]?.gracePeriodExpired).toBe(true)
  })
})