@digione/ngx-core

Angular client ของ DigiOne API: ยืนยัน site จากโดเมน (X-Client-Site), เข้าสู่ระบบผู้ใช้พร้อมต่ออายุ token อัตโนมัติ, และเรียก REST endpoint ใดก็ได้

| เวอร์ชัน | Angular | หมายเหตุ | |---|---|---| | 3.x | 22 | standalone (provideDigione), signals, รองรับ SSR, ไม่ใช้ lodash | | 2.x | 17 | DigioneModule.forRoot (tag v2.0.0) | | 1.x | 16 | tag v1.0.0 |

ย้ายจาก 2.x ดู docs/migration/v2-to-v3.md

ติดตั้ง

npm install @digione/ngx-core@^3

peer dependency: @angular/core, @angular/common >= 22, rxjs ^7.4

ตั้งค่า

// app.config.ts
import { provideHttpClient, withFetch } from '@angular/common/http';
import { provideDigione, provideLocalStorage } from '@digione/ngx-core';
import { environment } from '../environments/environment';

export const appConfig: ApplicationConfig = {
  providers: [
    provideHttpClient(withFetch()), // ต้องมี: library ใช้ HttpClient ของแอป
    provideDigione({
      scope: 'site',                 // 'site' | 'organ' | 'core' (ค่าเริ่มต้น 'organ')
      environment,                   // apiUrl, apiUrls, apiUrlSystem, customApiUrl, defaultDomain, production, isMobile, authDomainOption
      storage: provideLocalStorage(), // ค่าเริ่มต้นคือเก็บใน memory (หายเมื่อ reload)
    }),
  ],
};

| option | ความหมาย | |---|---| | scope | เลือก endpoint ของ auth และ prefix ของ key ใน storage: site → v1/sites/users/auth, key web_* · organ → v1/users/auth, key ไม่มี prefix · core → v1/core/users/auth, key core_* | | scopePrefix | แทนชื่อ module ของ auth เช่น 'site' → v1/site/users/auth | | environment | URL ของ API (ดูตารางด้านล่าง) | | storage | provideLocalStorage(), provideCustomStorage(() => storage) หรือ { provide: StorageProvider, useClass: ... } | | isServer | ค่าเริ่มต้นตรวจจาก PLATFORM_ID ฝั่ง server จะไม่อ่าน/เขียน storage | | tokenRef, site | ใช้ตอน SSR: site token และ site ของ request นั้น · ไม่ตั้ง tokenRef → GET ฝั่ง server ไม่ยิง request: single คืน null, list คืน { data: [], total: null } | | emptyOnNoContent | ค่าเริ่มต้น true: GET ที่ได้ 204 คืน null (single) หรือ { data: [], total: null, headers } (list) · false → reject { error: { code: 204 } } |

| field ใน environment | ใช้เมื่อ | |---|---| | apiUrl | base URL ปกติ (ไม่ใส่ = https://digioneapi.com) | | apiUrls | เลือกด้วย apiNumber (เริ่มที่ 1) | | customApiUrl | base URL ต่อ module เช่น { sites: 'https://...' } | | apiUrlSystem | request ที่ system: true (login, refresh, domain) ชนะทุกตัว | | defaultDomain, production, isMobile | โดเมนที่ใช้ต่ออายุ site token อัตโนมัติ: production && !isMobile → location.hostname ไม่งั้น defaultDomain | | authDomainOption | { include, query } ที่ส่งตอนต่ออายุ site token อัตโนมัติ |

config ที่ต้อง inject ค่าอื่น (เช่น SSR)

provideDigione(
  () => ({ scope: 'site', environment, tokenRef: inject(REQUEST_TOKEN_REF), site: inject(REQUEST_SITE) }),
  provideLocalStorage(), // storage ใส่เป็น argument ที่ 2 เมื่อใช้ factory
);

Ionic Storage

import { Storage } from '@ionic/storage-angular';

provideDigione({
  scope: 'site',
  environment,
  storage: provideCustomStorage(() => inject(Storage)),
}),
provideAppInitializer(() => inject(Storage).create()), // ต้อง create ก่อนมี request แรก

ใช้งาน

const site = inject(CoreSiteService);
const auth = inject(AuthService);
const custom = inject(CustomService);

// 1. ยืนยัน site (request อื่นที่ยิงก่อนหน้านี้จะรอจนได้ site token
//    ถ้า authDomain ล้ม request ที่รออยู่จะ reject ด้วย error เดียวกัน จนกว่าจะเรียก authDomain ใหม่)
await site.authDomain(location.hostname, { include: { setting: true } });

// 2. เรียก endpoint ใดก็ได้ด้วย "<module>/<path>"
const { data, total } = await custom.fetch.get('sites/web_languages', { query: { lang_code: 'th' } });
const product = await custom.fetch.get('site/products', { index: 15 }, { single: true });
const res = await custom.fetch.post('site/carts', { data: { product_id: 15, qty: 1 } }); // HttpResponse

// 3. ผู้ใช้
await auth.signInWithEmail(email, password);
auth.user();          // signal
auth.user$;           // observable
await auth.signOut();

| เรียก | ได้ | |---|---| | fetch.get (ไม่ใส่ single) | { data, total: number \| null, headers } (204 → { data: [], total: null, headers }) | | fetch.get(..., { single: true }), profile().object() | body (204 → null) | | fetch.post/put/delete, profile().create/update/delete/stream, signUpWithEmail, deleteAccount | HttpResponse ทั้งก้อน |

ทุก request ส่ง withCredentials: true, X-Client-Site และ Authorization: BEARER <access token> (เมื่อ access เป็น true ซึ่งเป็นค่าเริ่มต้นของ CustomService)

ต่ออายุ token อัตโนมัติ

• 401 SITE_REF_IS_NOT_AUTHORIZED → POST v1/core/domains/auth ใหม่ แล้วยิงซ้ำ 1 ครั้ง
• 401 TOKEN_EXPIRED / TOKEN_IS_INVALID → POST <auth>/refresh ด้วย refresh token แล้วยิงซ้ำ 1 ครั้ง ถ้า refresh ได้ 401 จะล้าง session และ user เป็น null
• request ที่เกิดพร้อมกันใช้การต่ออายุรอบเดียวกัน · ปิดได้ด้วย { error: false }

พัฒนา library

ดู CLAUDE.md และ docs/ARCHITECTURE.md ใน repo