54 lines
5.9 KiB
Markdown
54 lines
5.9 KiB
Markdown
## KriFrontCommon Consumer Contract
|
|
|
|
- Consume the published `@kri/common` package only through entry points declared by its `package.json` `exports` map.
|
|
- Do not import from `@kri/common/src/*`, `@kri/common/dist/*`, or another undeclared deep path.
|
|
- Prefer a public shared helper or an approved backward-compatible library addition over copying or forking shared behavior locally.
|
|
- Do not modify KriFrontCommon or another consumer repository unless it is explicitly included in the approved task scope.
|
|
|
|
### Required Shared References
|
|
|
|
Before each related task, read the current contents of every matching reference, even if it was read earlier in the session.
|
|
|
|
| Task scope | Required reference |
|
|
|---|---|
|
|
| Package entry points, runtime boundaries, HTTP, authentication, state, storage, environment, or optional peer integrations | `.agent-harness/references/kri-front-common/package-and-runtime.md` |
|
|
| React rendering performance, memoization, or React Compiler behavior | `.agent-harness/references/kri-front-common/react-compiler.md` |
|
|
| Package upgrade, dependency changes, lockfile, or verification | `.agent-harness/references/kri-front-common/change-and-verification.md` |
|
|
|
|
If a task spans multiple scopes, read every matching reference. Generated files under `.agent-harness/references/` are read-only copies; edit KriFrontCommon's `.agent/consumer.md` or `.agent/consumer-references/` and recompose instead.
|
|
|
|
## Class Name Helper
|
|
|
|
- `@kri/common/ui` exports `cn` and `ClassValue` from the npm `cn` package (pinned exactly). It replaces `clsx` + `tailwind-merge` with the same public signature and merge results; consumers keep importing `cn` through their `@/lib/utils` re-export.
|
|
- `@kri/common` now declares `engines.node >=22` because `cn` requires Node.js 22 or later.
|
|
- shadcn CLI may add `cn` to a consumer's own dependencies when installing components; that is expected and harmless.
|
|
|
|
## Noti-hub SMS Types
|
|
|
|
- `MessageType.SMS = 21`, `LMS = 22`, `MMS = 23`; `ChannelType.SMS = 2` is unchanged. `SMS_TYPE_ARRAY` and `SmsType` include all three.
|
|
- `LMS_MMS = 22` remains a deprecated source-compatibility alias for LMS only. It does not represent MMS. Enum reverse lookup for 22 returns LMS. Use numeric bulk-list paths; the server no longer accepts LMS_MMS in paths. Numeric 21/22/23 bulk-list requests all return the entire SMS channel, not type-filtered lists.
|
|
- Requests retain their existing URLs/body shapes. The server chooses the actual type per recipient after substitution: attachment -> MMS; otherwise title or UTF-8 body >= 90 bytes -> LMS; otherwise SMS.
|
|
- Refresh templates from the save response (`tmplatTy`); display actual delivery types from `sendTy`, not the template or result code. A bulk can contain multiple SMS types. LMS/MMS share result codes; use existing server result labels.
|
|
- SMS, LMS, MMS and KKO use cancellation code 9998. Verify with `npm run typecheck`, `npm run build`, and `node --test tests/noti-hub-sms.test.mjs`.
|
|
|
|
## Noti-hub Reservation Cancellation
|
|
|
|
- Import cancellation types, constants, and helpers from `@kri/common/noti-hub` only. They are runtime-neutral and require no optional peers.
|
|
- Individual current cancellation state is determined by resultCode via isReserveCanceledResult; bulk current state is cancellationStatus (NONE/PARTIAL/ALL). These describe current cancellation state, not cancellation eligibility. cancelDt and cancelUser are request history, not current state.
|
|
- SendResultInfo, SendInfo, and BulkSendInfo expose optional cancelable. Use isSendCancelable(item), which returns true only for cancelable === true, for cancellation eligibility; missing values from older responses are treated as false. Never infer eligibility from cancelDt, result labels, or result codes.
|
|
- cancelable reflects query-time state and may change before cancellation. Determine the final outcome from SendCancelResponse counts.
|
|
- sendIdx is the single-cancel identifier, not cmid. It is absent from the latest abbreviated report (/api/v1/report/last/send/...). Request sendIdx must be a positive integer; bulkSendKey is required and at most 32 characters.
|
|
- EMAIL_RESERVE_CANCELED_RESULT_CODE is 108 for EMAIL. SMS_KKO_RESERVE_CANCELED_RESULT_CODE is 9998 for SMS, LMS, MMS, and KKO. Unknown message types are not recognized as canceled.
|
|
- Display the server's resultViewLabel/resultLabel ("예약 취소"). There is no separate result-code list API.
|
|
- HTTP 200 can contain notCancelableCount. parseSendCancelResponse validates nonnegative integer counts and targetCount = canceledCount + alreadyCanceledCount + notCancelableCount, throwing TypeError on invalid data. Bulk targetCount counts currently registered detail rows; response canceledCount counts only cancellations made by that request.
|
|
- Existing response fields are unchanged; all added fields on existing types are optional. Verify with npm run typecheck and npm run build.
|
|
|
|
## HTTP Streaming
|
|
|
|
- `@kri/common/http` HTTP clients expose streamGet/streamPost/streamPut/streamPatch/streamDel, returning HttpStreamResponse (status, statusText, headers, url, nullable body).
|
|
- Streaming shares ordinary authentication, URL, body and HTTP-error policy. Read body incrementally; no automatic JSON/NDJSON/SSE parsing or reconnect is performed.
|
|
- Streaming options accept an external AbortSignal. Caller cancellation raises AbortError without an HTTP error notification. Cancel the body when it will not be consumed.
|
|
- timeoutMs covers connection/headers (and an HTTP error body); idleTimeoutMs covers inactivity after successful headers and resets on consumed chunks. Both default to the client's defaultTimeoutMs (60 seconds by default), and 0 disables that timer for streaming only.
|
|
- Mid-stream transport/time-out errors reach the body reader. HTTP error statuses use existing HttpError handlers before a stream is returned. A 204 response has body=null.
|
|
- See HTTP_STREAMING.md for examples and node --test tests/http-stream.test.mjs for focused validation after npm run build.
|