@likerts/react-native 0.0.3

package/src/choice-features.ts

@@ -0,0 +1,45 @@
+import type {Answer, Question} from './index';
+
+/** Selected option IDs have the same meaning across legacy and structured answers. */
+export function selectedChoices(value: unknown): string[] {
+  if (typeof value === 'string') return value ? [value] : [];
+  if (Array.isArray(value)) return value.filter((v): v is string => typeof v === 'string');
+  if (value && typeof value === 'object' && 'selected' in value && Array.isArray(value.selected)) return value.selected.filter((v): v is string => typeof v === 'string');
+  return [];
+}
+export function otherTexts(value: unknown): Record<string,string> {
+  if (!value || typeof value !== 'object' || !('otherText' in value) || !value.otherText || typeof value.otherText !== 'object' || Array.isArray(value.otherText)) return {};
+  return Object.fromEntries(Object.entries(value.otherText).filter((entry): entry is [string,string] => typeof entry[1] === 'string'));
+}
+export function choiceAnswer(q: Question, selected: string[], text: Record<string,string> = {}): Answer {
+  if (q.options?.some(o => o.other !== undefined)) return {selected:[...selected],otherText:Object.fromEntries((q.options ?? []).filter(o => o.other !== undefined && selected.includes(o.id)).map(o => [o.id,text[o.id] ?? '']))};
+  return q.type === 'single_choice' ? selected[0] ?? '' : [...selected];
+}
+export function toggleChoice(q: Question, value: unknown, id: string): Answer {
+  const option=q.options?.find(o=>o.id===id); if (!option) throw new TypeError('Unknown choice');
+  const current=selectedChoices(value);
+  const selected=q.type==='single_choice' ? [id] : current.includes(id) ? current.filter(v=>v!==id) : option.exclusive ? [id] : [...current.filter(v=>!q.options?.find(o=>o.id===v)?.exclusive),id];
+  return choiceAnswer(q,selected,otherTexts(value));
+}
+export function setOtherText(q: Question, value: unknown, id: string, text: string): Answer {
+  return choiceAnswer(q,selectedChoices(value),{...otherTexts(value),[id]:text});
+}
+/** Local feedback only; the server validates every accepted answer again. */
+export function choiceError(q: Question, value: unknown): 'required'|'range'|'other'|'invalid'|undefined {
+  if (value === undefined || value === '') return q.required ? 'required' : undefined;
+  const hasOther=q.options?.some(o=>o.other !== undefined);
+  if (hasOther) {
+    if (!value || typeof value!=='object' || Array.isArray(value) || Object.keys(value).length!==2 || !('selected' in value) || !Array.isArray(value.selected) || !value.selected.every(v=>typeof v==='string') || !('otherText' in value) || !value.otherText || typeof value.otherText!=='object' || Array.isArray(value.otherText)) return 'invalid';
+  } else if (q.type==='single_choice' ? typeof value!=='string' : !Array.isArray(value) || !value.every(v=>typeof v==='string')) return 'invalid';
+  const selected=selectedChoices(value);
+  if (new Set(selected).size!==selected.length || selected.some(id=>!q.options?.some(o=>o.id===id))) return 'invalid';
+  const exclusive=selected.some(id=>q.options?.some(o=>o.id===id && o.exclusive));
+  if (exclusive && selected.length!==1) return 'invalid';
+  if (q.type==='single_choice' ? selected.length!==1 : selected.length>(q.maxSelections??q.options?.length??0) || (!exclusive && selected.length<Math.max(q.required?1:0,q.minSelections??0))) return 'range';
+  if (hasOther) {
+    const text=otherTexts(value),expected=(q.options??[]).filter(o=>o.other!==undefined && selected.includes(o.id));
+    if (Object.keys((value as {otherText:object}).otherText).length!==expected.length) return 'other';
+    if (expected.some(o=>typeof text[o.id]!=='string' || !text[o.id].trim() || Array.from(text[o.id]).length>o.other!.maxLength)) return 'other';
+  }
+  return undefined;
+}

package/src/index.ts

@@ -0,0 +1,54 @@
+export interface StructuredChoiceAnswer {selected:string[];otherText:Record<string,string>}
+export type Answer = string | number | string[] | StructuredChoiceAnswer | Record<string,string|string[]> | Record<string,number>;
+export type QuestionType = 'single_choice' | 'multiple_choice' | 'scale' | 'text' | 'number' | 'date' | 'ranking' | 'matrix' | 'constant_sum';
+export type VisibilityOperator='equals'|'not_equals'|'includes'|'not_includes'|'answered'|'not_answered';
+export interface VisibilityCondition {questionId:string;operator:VisibilityOperator;value?:string|number}
+export interface PageBranch {when:VisibilityCondition;goToPageId:string}
+export interface SurveyPage {id:string;title?:string;questionIds:string[];branches?:PageBranch[]}
+export interface Choice {id:string;label:string;other?:{maxLength:number};exclusive?:true}
+export interface PromptItem{id:string;label:string}
+export interface Question { id: string; type: QuestionType; label: string; required?: boolean; options?: Choice[]; min?: number; max?: number; maxLength?: number; preset?: 'nps' | 'yes_no'; labels?: Record<string, string>; minSelections?: number; maxSelections?: number; visibleWhen?:VisibilityCondition; presentation?:'stars'|'dropdown';rows?:PromptItem[];columns?:Choice[];matrixMode?:'single'|'multiple';items?:PromptItem[];total?:number }
+export interface Collection { id: string; surveyId: string; version: number; placement: string; schema: { schemaVersion: 1 | 2 | 3 | 4 | 5; title: string; questions: Question[]; pages?:SurveyPage[] } }
+export interface Submission { idempotencyKey: string; answers: Record<string, Answer>; metadata: Record<string, unknown> }
+export interface Receipt { responseId: string; collectionId: string; accepted: true }
+export interface RequestOptions { signal?: AbortSignal; timeoutMs?: number }
+export interface CollectionRequestOptions extends RequestOptions { refresh?: boolean }
+export const LIKERTS_SDK_CAPABILITY = Object.freeze({target:'react_native' as const,sdkVersion:'0.0.3',schemaVersions:[1,2,3,4,5] as const});
+export class LikertsError extends Error { constructor(public status: number, public response: string) { super(`Likerts request failed (${status})`); } }
+function safeBaseURL(value: string): string {
+  const url = new URL(value); const loopback = url.hostname === 'localhost' || url.hostname === '127.0.0.1' || url.hostname === '[::1]';
+  if ((url.protocol !== 'https:' && !(url.protocol === 'http:' && loopback)) || url.username || url.password || url.search || url.hash) throw new TypeError('Likerts base URL must use HTTPS (HTTP is limited to loopback development)');
+  return value.replace(/\/$/, '');
+}
+/** Only a public collection credential belongs here. No administrative credentials. */
+export class LikertsClient {
+  private baseURL: string;
+  private transport: typeof fetch;
+  private collectionCache = new Map<string,{value:Collection;storedAt:number}>();
+  constructor(baseURL: string, private token: string, transport: typeof fetch | undefined = undefined, private defaultTimeoutMs = 15000, private cacheMaxAgeMs = 300000) { this.baseURL = safeBaseURL(baseURL);this.transport=transport??((input,init)=>globalThis.fetch(input,init)); if (!Number.isFinite(defaultTimeoutMs) || defaultTimeoutMs <= 0) throw new TypeError('timeoutMs must be positive'); if (!Number.isFinite(cacheMaxAgeMs) || cacheMaxAgeMs < 0) throw new TypeError('cacheMaxAgeMs must not be negative'); }
+  private async request<T>(path: string, body?: Submission, options: RequestOptions = {}): Promise<T> {
+    const timeoutMs = options.timeoutMs ?? this.defaultTimeoutMs; if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) throw new TypeError('timeoutMs must be positive');
+    const controller = new AbortController(); const abort = () => controller.abort(options.signal?.reason);
+    if (options.signal?.aborted) abort(); else options.signal?.addEventListener('abort', abort, {once: true});
+    const timer = setTimeout(() => controller.abort(new Error('Likerts request timed out')), timeoutMs);
+    try {
+      const response = await this.transport(`${this.baseURL}${path}`, { method: body ? 'POST' : 'GET', redirect: 'error', signal: controller.signal, headers: { Authorization: `Bearer ${this.token}`, ...(body ? {'Content-Type': 'application/json'} : {}) }, ...(body ? {body: JSON.stringify(body)} : {}) });
+      if (!response.ok) throw new LikertsError(response.status, await response.text());
+      return await response.json() as T;
+    } finally { clearTimeout(timer); options.signal?.removeEventListener('abort', abort); }
+  }
+  async collection(id: string, options: CollectionRequestOptions = {}): Promise<Collection> { const cached=this.collectionCache.get(id);if(!options.refresh&&cached&&Date.now()-cached.storedAt<this.cacheMaxAgeMs)return cached.value;
+    try { const c=await this.request<Collection>(`/v1/collections/${encodeURIComponent(id)}`,undefined,options);if(![1,2,3,4,5].includes(c.schema.schemaVersion))throw new Error('Unsupported survey schema version');if(cached&&(cached.value.id!==c.id||cached.value.surveyId!==c.surveyId||cached.value.version!==c.version||cached.value.schema.schemaVersion!==c.schema.schemaVersion)){this.collectionCache.delete(id);throw new Error('Collection binding changed');}this.collectionCache.set(id,{value:c,storedAt:Date.now()});return c;}catch(error){this.collectionCache.delete(id);throw error;} }
+  clearCollectionCache(id?:string):void{if(id)this.collectionCache.delete(id);else this.collectionCache.clear();}
+  /** Retrying requires the same submission object, including its idempotencyKey. */
+  async submit(id: string, submission: Submission, options?: RequestOptions): Promise<Receipt> { const receipt = await this.request<Receipt>(`/v1/collections/${encodeURIComponent(id)}/responses`, submission, options); if (receipt.accepted !== true) throw new Error('Invalid Likerts receipt'); return receipt; }
+}
+export function conditionMatches(condition:VisibilityCondition,answer:Answer|undefined):boolean{const selected=answer&&typeof answer==='object'&&!Array.isArray(answer)&&'selected'in answer&&Array.isArray(answer.selected)?answer.selected as string[]:undefined;const objectAnswer=answer&&typeof answer==='object'&&!Array.isArray(answer);const hasAnswer=answer!==undefined&&(typeof answer!=='string'||answer.trim()!=='')&&(!Array.isArray(answer)||answer.length>0)&&(!objectAnswer||(selected?selected.length>0:Object.keys(answer).length>0));if(condition.operator==='answered')return hasAnswer;if(condition.operator==='not_answered')return !hasAnswer;if(answer===undefined||answer==='')return false;const scalar=selected?.length===1?selected[0]:answer;if(condition.operator==='equals')return scalar===condition.value;if(condition.operator==='not_equals')return scalar!==condition.value;const values=selected??(Array.isArray(answer)?answer:undefined);if(!values)return false;if(condition.operator==='includes')return values.includes(String(condition.value));if(condition.operator==='not_includes')return !values.includes(String(condition.value));throw new Error('Unsupported visibility operator')}
+export function visibleQuestionIds(questions:Question[],answers:Record<string,Answer>):Set<string>{const byId=new Map(questions.map(q=>[q.id,q]));const memo=new Map<string,boolean>();const active=new Set<string>();const visible=(q:Question):boolean=>{const prior=memo.get(q.id);if(prior!==undefined)return prior;if(active.has(q.id))throw new Error('Conditional visibility cycle');active.add(q.id);let result=true;if(q.visibleWhen){const source=byId.get(q.visibleWhen.questionId);if(!source)throw new Error('Conditional visibility references an unknown question');result=conditionMatches(q.visibleWhen,visible(source)?answers[source.id]:undefined)}active.delete(q.id);memo.set(q.id,result);return result};return new Set(questions.filter(visible).map(q=>q.id))}
+export function visibleAnswers(questions:Question[],answers:Record<string,Answer>):Record<string,Answer>{const visible=visibleQuestionIds(questions,answers);return Object.fromEntries(Object.entries(answers).filter(([id])=>visible.has(id)))}
+export {SurveyFlow,pageRoute,routedAnswers} from './branching';
+export type {BranchingSchema,SurveyProgress} from './branching';
+export {Survey} from './Survey';
+export type {SurveyMessages, SurveyProps, SurveyStyles} from './Survey';
+export {SurveyHost} from './SurveyHost';
+export type {SurveyHostMessages, SurveyHostProps} from './SurveyHost';

package/src/offline.ts

@@ -0,0 +1,35 @@
+import type {Receipt,Submission} from './index';
+
+export type OfflineReason='invalid'|'conflict'|'unauthorized'|'revoked'|'deleted'|'expired';
+export type OfflineState='pending'|'blocked'|'expired_local';
+export interface OfflineLimits{maxRecords:number;maxBytes:number;maxAgeSeconds:number}
+export interface OfflineStatus{pending:number;blockedByReason:Partial<Record<OfflineReason,number>>;expiredLocal:number;quarantined:number;bytes:number}
+export interface OfflineOutcome{recordId:string;outcome:'accepted'|'retry'|'blocked'|'expired_local'|'quarantined'|'credential_unavailable';reason?:OfflineReason;retryAfterSeconds?:number}
+export interface FlushReport{attempted:number;accepted:number;pending:number;blocked:number;expiredLocal:number;quarantined:number;cancelled:boolean;outcomes:OfflineOutcome[]}
+export interface OpaqueQueueStore{load():Promise<Uint8Array[]>;replace(records:readonly Uint8Array[]):Promise<void>}
+export interface QueueCipher{seal(cleartext:Uint8Array):Promise<Uint8Array>;open(ciphertext:Uint8Array):Promise<Uint8Array>}
+export interface OfflineSendResult{status:number;receipt?:Receipt;retryAfterSeconds?:number}
+export type OfflineSender=(collectionId:string,credential:string,submission:Submission,signal?:AbortSignal)=>Promise<OfflineSendResult>;
+type RecordData={id:string;collectionId:string;submissionText:string;createdAt:number;byteSize:number;attemptCount:number;state:OfflineState;reason?:OfflineReason};
+const DEFAULTS:OfflineLimits={maxRecords:1000,maxBytes:10*1024*1024,maxAgeSeconds:7*86400},HARD={maxRecords:10000,maxBytes:100*1024*1024,maxAgeSeconds:30*86400},MAX_RECORD=65536;
+const encoder=new TextEncoder(),decoder=new TextDecoder();
+const canonical=(value:unknown):string=>JSON.stringify(value&&typeof value==='object'&&!Array.isArray(value)?Object.fromEntries(Object.entries(value as Record<string,unknown>).sort(([a],[b])=>a.localeCompare(b)).map(([k,v])=>[k,JSON.parse(canonical(v))])):Array.isArray(value)?value.map(v=>JSON.parse(canonical(v))):value);
+const reason=(status:number):OfflineReason|undefined=>({400:'invalid',409:'conflict',401:'unauthorized',403:'revoked',404:'deleted',410:'expired'} as Record<number,OfflineReason>)[status]??(status>=400&&status<500&&![408,425,429].includes(status)?'invalid':undefined);
+const retryable=(status:number)=>[408,425,429].includes(status)||status>=500;
+const limits=(value:Partial<OfflineLimits>):OfflineLimits=>{const result={...DEFAULTS,...value};if(!Number.isSafeInteger(result.maxRecords)||result.maxRecords<1||result.maxRecords>HARD.maxRecords||!Number.isSafeInteger(result.maxBytes)||result.maxBytes<1||result.maxBytes>HARD.maxBytes||!Number.isSafeInteger(result.maxAgeSeconds)||result.maxAgeSeconds<1||result.maxAgeSeconds>HARD.maxAgeSeconds)throw new RangeError('Offline queue limits exceed hard bounds');return result};
+
+export interface NativeOfflineAdapter extends OpaqueQueueStore,QueueCipher { readonly secureKeyProfile:'keychain'|'android_keystore'; readonly encryptedStorage:true;createRecordId():string }
+export function openNativeOfflineQueue(adapter:NativeOfflineAdapter,sender:OfflineSender,configuration:Partial<OfflineLimits>={}):OfflineQueue{if(adapter.encryptedStorage!==true||!['keychain','android_keystore'].includes(adapter.secureKeyProfile))throw new Error('A native encrypted storage and secure key adapter is required');return new OfflineQueue(adapter,adapter,sender,configuration,undefined,()=>adapter.createRecordId())}
+
+export class OfflineQueue{
+ private readonly configuration:OfflineLimits;private flushing=false;
+ constructor(private store:OpaqueQueueStore,private cipher:QueueCipher,private sender:OfflineSender,configuration:Partial<OfflineLimits>={},private now:()=>number=()=>Date.now(),private randomId:()=>string=()=>{throw new Error('A native secure random record ID adapter is required')}){this.configuration=limits(configuration)}
+ private async read(){const good:{record:RecordData;ciphertext:Uint8Array}[]=[],bad:Uint8Array[]=[];for(const ciphertext of await this.store.load()){try{good.push({record:JSON.parse(decoder.decode(await this.cipher.open(ciphertext))),ciphertext})}catch{bad.push(ciphertext)}}return{good,bad}}
+ private async write(records:RecordData[],bad:Uint8Array[]){await this.store.replace([...bad,...await Promise.all(records.map(r=>this.cipher.seal(encoder.encode(canonical(r)))) )])}
+ async enqueue(collectionId:string,submission:Submission){if(!collectionId||!submission.idempotencyKey)throw new TypeError('collectionId and idempotencyKey are required');const submissionText=canonical(submission),byteSize=encoder.encode(submissionText).byteLength;if(byteSize>MAX_RECORD)throw new RangeError('Offline record exceeds 64 KiB');const {good,bad}=await this.read(),records=good.map(v=>v.record),prior=records.find(r=>JSON.parse(r.submissionText).idempotencyKey===submission.idempotencyKey);if(prior){if(prior.collectionId!==collectionId||prior.submissionText!==submissionText)throw new Error('Offline idempotency conflict');return prior.id}if(records.length>=this.configuration.maxRecords||records.reduce((sum,r)=>sum+r.byteSize,0)+byteSize>this.configuration.maxBytes)throw new RangeError('Offline queue capacity exceeded');const record={id:this.randomId(),collectionId,submissionText,createdAt:this.now(),byteSize,attemptCount:0,state:'pending' as const};await this.write([...records,record],bad);return record.id}
+ async snapshot():Promise<OfflineStatus>{const {good,bad}=await this.read(),status:OfflineStatus={pending:0,blockedByReason:{},expiredLocal:0,quarantined:bad.length,bytes:0};for(const {record:r} of good){status.bytes+=r.byteSize;if(r.state==='pending')status.pending++;else if(r.state==='expired_local')status.expiredLocal++;else if(r.reason)status.blockedByReason[r.reason]=(status.blockedByReason[r.reason]??0)+1}return status}
+ async delete(recordId:string){const {good,bad}=await this.read();await this.write(good.map(v=>v.record).filter(r=>r.id!==recordId),bad)}
+ async deleteCollection(collectionId:string){const {good,bad}=await this.read(),kept=good.map(v=>v.record).filter(r=>r.collectionId!==collectionId);const count=good.length-kept.length;await this.write(kept,bad);return count}
+ async purgeQuarantined(){const {good,bad}=await this.read();await this.write(good.map(v=>v.record),[]);return bad.length}
+ async flush(resolveCredential:(collectionId:string)=>Promise<string|undefined>,signal?:AbortSignal):Promise<FlushReport>{if(this.flushing)throw new Error('Offline flush already active');this.flushing=true;const report:FlushReport={attempted:0,accepted:0,pending:0,blocked:0,expiredLocal:0,quarantined:0,cancelled:false,outcomes:[]};try{const initial=await this.read(),initialRecords=initial.good.map(v=>v.record);let expiredChanged=false;for(const record of initialRecords){if(record.state!=='expired_local'&&this.now()-record.createdAt>this.configuration.maxAgeSeconds*1000){record.state='expired_local';delete record.reason;expiredChanged=true}}if(expiredChanged)await this.write(initialRecords,initial.bad);const ids=initialRecords.filter(r=>r.state==='pending').sort((a,b)=>a.createdAt-b.createdAt||a.id.localeCompare(b.id)).map(r=>r.id);for(const id of ids){if(signal?.aborted){report.cancelled=true;break}const current=await this.read(),records=current.good.map(v=>v.record),record=records.find(r=>r.id===id);if(!record||record.state!=='pending')continue;const credential=await resolveCredential(record.collectionId);if(!credential){report.pending++;report.outcomes.push({recordId:id,outcome:'credential_unavailable'});continue}report.attempted++;let result:OfflineSendResult|undefined;try{result=await this.sender(record.collectionId,credential,JSON.parse(record.submissionText),signal)}catch{}const fresh=await this.read(),updated=fresh.good.map(v=>v.record),target=updated.find(r=>r.id===id);if(!target)continue;const receipt=result?.receipt;if(result&&result.status>=200&&result.status<300&&receipt?.accepted===true&&receipt.collectionId===target.collectionId&&receipt.responseId.length>0){await this.write(updated.filter(r=>r.id!==id),fresh.bad);report.accepted++;report.outcomes.push({recordId:id,outcome:'accepted'});continue}target.attemptCount++;const terminal=result&&reason(result.status);if(terminal){target.state='blocked';target.reason=terminal;report.blocked++;report.outcomes.push({recordId:id,outcome:'blocked',reason:terminal})}else{report.pending++;report.outcomes.push({recordId:id,outcome:'retry',...(result?.retryAfterSeconds!==undefined&&retryable(result.status)?{retryAfterSeconds:Math.max(0,Math.min(86400,Math.floor(result.retryAfterSeconds)))}:{})})}await this.write(updated,fresh.bad)}}finally{this.flushing=false}const final=await this.snapshot();report.pending=final.pending;report.quarantined=final.quarantined;report.expiredLocal=final.expiredLocal;report.blocked=Object.values(final.blockedByReason).reduce((a,b)=>a+(b??0),0);return report}
+}