@beeblock/svelar 0.4.0

package/dist/hooks/index.d.ts

@@ -0,0 +1,135 @@
+/**
+ * Svelar Hooks
+ *
+ * Integration with SvelteKit's hooks system.
+ * Provides a Laravel-like middleware pipeline for all incoming requests.
+ *
+ * @module svelar/hooks
+ *
+ * @example Simple (auto-wired defaults)
+ * ```ts
+ * // src/hooks.server.ts
+ * import { createSvelarApp } from 'svelar/hooks';
+ * import { auth } from './app';
+ *
+ * export const { handle, handleError } = createSvelarApp({ auth });
+ * ```
+ *
+ * @example Advanced (manual pipeline)
+ * ```ts
+ * import { createSvelarHooks } from 'svelar/hooks';
+ * import { CorsMiddleware } from 'svelar/middleware';
+ *
+ * export const handle = createSvelarHooks({
+ *   middleware: [CorsMiddleware],
+ * });
+ * ```
+ */
+import { Middleware, type MiddlewareHandler } from '../middleware/Middleware.js';
+import { Application } from '../container/Application.js';
+import { type SessionStore } from '../session/Session.js';
+import { type AuthManager } from '../auth/Auth.js';
+import { type ErrorHandlerConfig } from '../errors/Handler.js';
+export interface SvelarHooksConfig {
+    /** Global middleware to run on every request */
+    middleware?: Array<(new () => Middleware) | Middleware | MiddlewareHandler>;
+    /** Named middleware for per-route usage */
+    namedMiddleware?: Record<string, (new () => Middleware) | Middleware | MiddlewareHandler>;
+    /** Error handler */
+    onError?: (error: unknown, event: any) => void | Response | Promise<void | Response>;
+    /** Application instance (optional — for DI integration) */
+    app?: Application;
+}
+export interface SvelarAppConfig {
+    /** Auth manager instance */
+    auth?: AuthManager;
+    /** Session secret key (defaults to APP_KEY env var) */
+    secret?: string;
+    /** Session store (default: MemorySessionStore — lost on restart) */
+    sessionStore?: SessionStore;
+    /** Session lifetime in seconds (default: 86400 = 24h) */
+    sessionLifetime?: number;
+    /** Rate limit: max requests per window (default: 100) */
+    rateLimit?: number;
+    /** Rate limit: window in ms (default: 60000 = 1min) */
+    rateLimitWindow?: number;
+    /** CSRF: paths to protect (default: ['/api/']) */
+    csrfPaths?: string[];
+    /** CSRF: paths to exclude (default: ['/api/webhooks']) */
+    csrfExcludePaths?: string[];
+    /** Auth throttle: max login attempts (default: 5) */
+    authThrottleAttempts?: number;
+    /** Auth throttle: decay in minutes (default: 1) */
+    authThrottleDecay?: number;
+    /** Enable debug error output (default: auto from NODE_ENV) */
+    debug?: boolean;
+    /** Additional global middleware to append */
+    middleware?: Array<(new () => Middleware) | Middleware | MiddlewareHandler>;
+    /** Named middleware for per-route usage */
+    namedMiddleware?: Record<string, (new () => Middleware) | Middleware | MiddlewareHandler>;
+    /** i18n configuration — if provided, auto-wires paraglide */
+    i18n?: {
+        paraglideMiddleware: (request: Request, callback: (args: {
+            request: Request;
+            locale: string;
+        }) => Response | Promise<Response>) => Response | Promise<Response>;
+        getTextDirection?: (locale: string) => string;
+    };
+    /** Error handler config overrides */
+    errorConfig?: Partial<ErrorHandlerConfig>;
+}
+/**
+ * Creates a fully-wired SvelteKit hooks setup with sensible defaults.
+ * One-liner setup inspired by Laravel's bootstrap.
+ *
+ * Returns `{ handle, handleError }` ready to export from hooks.server.ts.
+ *
+ * @example
+ * ```ts
+ * import { createSvelarApp } from 'svelar/hooks';
+ * import { auth } from './app';
+ *
+ * export const { handle, handleError } = createSvelarApp({ auth });
+ * ```
+ *
+ * @example With i18n
+ * ```ts
+ * import { createSvelarApp } from 'svelar/hooks';
+ * import { auth } from './app';
+ * import { paraglideMiddleware } from '$lib/paraglide/server';
+ * import { getTextDirection } from '$lib/paraglide/runtime';
+ *
+ * export const { handle, handleError } = createSvelarApp({
+ *   auth,
+ *   i18n: { paraglideMiddleware, getTextDirection },
+ * });
+ * ```
+ */
+export declare function createSvelarApp(appConfig?: SvelarAppConfig): {
+    handle: any;
+    handleError: (input: {
+        error: unknown;
+        event: any;
+        status: number;
+        message: string;
+    }) => any;
+};
+/**
+ * Creates a SvelteKit `handle` hook with Svelar middleware pipeline.
+ * For advanced use when you want full control over the middleware stack.
+ */
+export declare function createSvelarHooks(hookConfig?: SvelarHooksConfig): ({ event, resolve, }: {
+    event: any;
+    resolve: (event: any) => Promise<Response>;
+}) => Promise<Response>;
+/**
+ * Sequence multiple SvelteKit handle hooks together.
+ * Similar to SvelteKit's `sequence` helper.
+ */
+export declare function sequence(...handlers: Array<(opts: {
+    event: any;
+    resolve: (event: any) => Promise<Response>;
+}) => Promise<Response>>): ({ event, resolve, }: {
+    event: any;
+    resolve: (event: any) => Promise<Response>;
+}) => Promise<Response>;

package/dist/hooks/index.js

@@ -0,0 +1,5 @@
+var se=(a,e)=>()=>(a&&(e=a(a=0)),e);function X(a,e){let t=Symbol.for(a),n=globalThis;return n[t]||(n[t]=e()),n[t]}var B=se(()=>{"use strict"});var l=class{},m=class{middleware=[];namedMiddleware=new Map;use(e){return typeof e=="function"&&"prototype"in e&&typeof e.prototype?.handle=="function"?this.middleware.push(new e):this.middleware.push(e),this}register(e,t){return typeof t=="function"&&"prototype"in t&&typeof t.prototype?.handle=="function"?this.namedMiddleware.set(e,new t):this.namedMiddleware.set(e,t),this}get(e){return this.namedMiddleware.get(e)}async execute(e,t,n){let s=[...this.middleware];if(n)for(let i of n){let o=this.namedMiddleware.get(i);o&&s.push(o)}let r=t;for(let i=s.length-1;i>=0;i--){let o=s[i],c=r;typeof o.handle=="function"?r=()=>o.handle(e,c):r=()=>o(e,c)}return r()}count(){return this.middleware.length}};var w=class extends l{requests=new Map;maxRequests;windowMs;constructor(e={}){super(),this.maxRequests=e.maxRequests??60,this.windowMs=e.windowMs??6e4}async handle(e,t){let n=e.event.request.headers.get("x-forwarded-for")??e.event.getClientAddress?.()??"unknown",s=Date.now(),r=this.requests.get(n);if(r&&s<r.resetAt){if(r.count>=this.maxRequests)return new Response(JSON.stringify({error:"Too many requests"}),{status:429,headers:{"Content-Type":"application/json","Retry-After":String(Math.ceil((r.resetAt-s)/1e3))}});r.count++}else this.requests.set(n,{count:1,resetAt:s+this.windowMs});return t()}};var y=class extends l{cookieName;headerName;fieldName;excludePaths;onlyPaths;constructor(e={}){super(),this.cookieName=e.cookieName??"XSRF-TOKEN",this.headerName=e.headerName??"X-CSRF-Token",this.fieldName=e.fieldName??"_csrf",this.excludePaths=e.excludePaths??[],this.onlyPaths=e.onlyPaths??null}async handle(e,t){let{event:n}=e,s=n.request.method.toUpperCase();if(["GET","HEAD","OPTIONS"].includes(s))return this.setTokenAndContinue(e,t);if((n.request.headers.get("authorization")??"").startsWith("Bearer "))return t();let i=n.url.pathname;if(this.onlyPaths&&!this.onlyPaths.some(u=>i.startsWith(u)))return this.setTokenAndContinue(e,t);if(this.excludePaths.some(u=>i.startsWith(u)))return t();let o=this.getCookieToken(n),c=n.request.headers.get(this.headerName)??await this.getBodyToken(n);return!o||!c||!this.timingSafeEqual(o,c)?new Response(JSON.stringify({message:"CSRF token mismatch"}),{status:419,headers:{"Content-Type":"application/json"}}):t()}async setTokenAndContinue(e,t){let n=await t();if(!(n instanceof Response))return n;let r=this.getCookieToken(e.event)||this.generateToken();return n.headers.append("Set-Cookie",`${this.cookieName}=${r}; Path=/; SameSite=Lax`),n}getCookieToken(e){let n=(e.request.headers.get("cookie")??"").match(new RegExp(`${this.cookieName}=([^;]+)`));return n?n[1]:null}async getBodyToken(e){try{let t=e.request.headers.get("content-type")??"";if(t.includes("application/x-www-form-urlencoded")||t.includes("multipart/form-data"))return(await e.request.clone().formData()).get(this.fieldName);if(t.includes("application/json"))return(await e.request.clone().json())[this.fieldName]??null}catch{}return null}generateToken(){let e=new Uint8Array(32);return crypto.getRandomValues(e),Array.from(e,t=>t.toString(16).padStart(2,"0")).join("")}timingSafeEqual(e,t){if(e.length!==t.length)return!1;let n=new TextEncoder,s=n.encode(e),r=n.encode(t),i=0;for(let o=0;o<s.length;o++)i|=s[o]^r[o];return i===0}},v=class extends l{allowedOrigins;constructor(e={}){super(),this.allowedOrigins=new Set(e.allowedOrigins??[])}async handle(e,t){let{event:n}=e,s=n.request.method.toUpperCase();if(["GET","HEAD","OPTIONS"].includes(s)||(n.request.headers.get("authorization")??"").startsWith("Bearer "))return t();let i=n.request.headers.get("origin");if(!i)return t();let o=n.url.origin;return i===o||this.allowedOrigins.has(i)?t():new Response(JSON.stringify({message:"Cross-origin request blocked"}),{status:403,headers:{"Content-Type":"application/json"}})}};var E=class extends l{attempts=new Map;maxAttempts;decayMinutes;constructor(e={}){super(),this.maxAttempts=e.maxAttempts??5,this.decayMinutes=e.decayMinutes??1}async handle(e,t){let s=`${e.event.request.headers.get("x-forwarded-for")??e.event.getClientAddress?.()??"unknown"}:${e.event.url.pathname}`,r=Date.now(),i=this.attempts.get(s);if(i){if(r<i.blockedUntil){let c=Math.ceil((i.blockedUntil-r)/1e3);return new Response(JSON.stringify({message:"Too many attempts. Please try again later.",retry_after:c}),{status:429,headers:{"Content-Type":"application/json","Retry-After":String(c)}})}if(i.count>=this.maxAttempts){i.blockedUntil=r+this.decayMinutes*6e4,i.count=0;let c=this.decayMinutes*60;return new Response(JSON.stringify({message:"Too many attempts. Please try again later.",retry_after:c}),{status:429,headers:{"Content-Type":"application/json","Retry-After":String(c)}})}}let o=await t();if(o instanceof Response&&o.status>=400&&o.status<500){let c=this.attempts.get(s)??{count:0,blockedUntil:0};if(c.count++,this.attempts.set(s,c),this.attempts.size>1e4)for(let[u,N]of this.attempts)r>N.blockedUntil+this.decayMinutes*6e4*2&&this.attempts.delete(u)}return o}};import{randomBytes as re,createHmac as V,timingSafeEqual as ie}from"crypto";import{promises as me}from"fs";import{join as ye}from"path";var x=class a{constructor(e,t){this.id=e;t&&(this.data={...t},this.data._flash&&(this.previousFlashData=this.data._flash,delete this.data._flash))}data={};dirty=!1;flashData={};previousFlashData={};get(e,t){return e in this.flashData?this.flashData[e]:e in this.previousFlashData?this.previousFlashData[e]:e in this.data?this.data[e]:t}set(e,t){this.data[e]=t,this.dirty=!0}has(e){return e in this.data||e in this.flashData||e in this.previousFlashData}forget(e){delete this.data[e],this.dirty=!0}flush(){this.data={},this.dirty=!0}flash(e,t){this.flashData[e]=t,this.dirty=!0}all(){return{...this.data,...this.previousFlashData,...this.flashData}}isDirty(){return this.dirty||Object.keys(this.flashData).length>0}toPersist(){let e={...this.data};return Object.keys(this.flashData).length>0&&(e._flash=this.flashData),e}regenerateId(){let e=this.id,t=a.generateId();this.id=t,this.dirty=!0;let n=p.get(e);return n instanceof g&&n.markOldSessionId(e),p.delete(e),t}static generateId(){return re(32).toString("hex")}},p=new Map,g=class{sessions=new Map;oldSessionIds=new Set;async read(e){if(this.oldSessionIds.has(e))return null;let t=this.sessions.get(e);return t?Date.now()>t.expiresAt?(this.sessions.delete(e),null):t.data:null}async write(e,t,n){this.sessions.set(e,{data:t,expiresAt:Date.now()+n*1e3}),p.set(e,this)}async destroy(e){this.sessions.delete(e),p.delete(e)}async gc(e){let t=Date.now();for(let[n,s]of this.sessions)t>s.expiresAt&&(this.sessions.delete(n),p.delete(n))}markOldSessionId(e){this.oldSessionIds.add(e),this.sessions.delete(e)}};var T=class extends l{config;constructor(e){super(),this.config={cookieName:"svelar_session",lifetime:7200,secret:process.env.APP_KEY??(()=>{throw new Error("APP_KEY is not set. Set it in your .env file before using sessions.")})(),path:"/",domain:"",secure:process.env.NODE_ENV==="production",httpOnly:!0,sameSite:"lax",...e}}async handle(e,t){let n=e.event.request.headers.get("cookie")??"",s=this.getSessionIdFromCookie(n),r=null;if(s){let c=this.verifySignedId(s);c?(r=await this.config.store.read(c),s=c):s=null}s||(s=x.generateId());let i=new x(s,r??{});e.event.locals.session=i,e.locals.session=i;let o=await t();if(i.isDirty()&&await this.config.store.write(i.id,i.toPersist(),this.config.lifetime),o instanceof Response){let c=this.signId(i.id),u=this.buildCookieString(c);o.headers.append("Set-Cookie",u)}return o}getSessionIdFromCookie(e){let t=e.split(";").map(n=>n.trim());for(let n of t){let[s,...r]=n.split("=");if(s===this.config.cookieName)return decodeURIComponent(r.join("="))}return null}signId(e){let t=V("sha256",this.config.secret).update(e).digest("base64url");return`${e}.${t}`}verifySignedId(e){let t=e.lastIndexOf(".");if(t===-1)return null;let n=e.slice(0,t),s=e.slice(t+1),r=V("sha256",this.config.secret).update(n).digest("base64url");if(s.length!==r.length)return null;let i=Buffer.from(s),o=Buffer.from(r);if(i.length!==o.length)return null;try{if(ie(i,o))return n}catch{}return null}buildCookieString(e){let t=[`${this.config.cookieName}=${encodeURIComponent(e)}`];return t.push(`Path=${this.config.path}`),t.push(`Max-Age=${this.config.lifetime}`),this.config.domain&&t.push(`Domain=${this.config.domain}`),this.config.secure&&t.push("Secure"),this.config.httpOnly&&t.push("HttpOnly"),t.push(`SameSite=${this.config.sameSite}`),t.join("; ")}};import{createHmac as Te,randomBytes as be}from"crypto";var b=class extends l{constructor(t){super();this.authManager=t}async handle(t,n){let s=null;if(t.event.locals.session&&(s=await this.authManager.resolveFromSession(t.event.locals.session)),!s){let r=t.event.request.headers.get("authorization");if(r?.startsWith("Bearer ")){let i=r.slice(7);try{s=await this.authManager.resolveFromToken(i)}catch{s=await this.authManager.resolveFromApiToken(i)}}}return t.event.locals.user=s,t.event.locals.auth=this.authManager,n()}};B();import{appendFile as ae,mkdir as oe}from"fs/promises";import{dirname as ce}from"path";var S={debug:0,info:1,warn:2,error:3,fatal:4},f=class{minLevel;format;constructor(e){this.minLevel=e.level??"debug",this.format=e.format??"text"}write(e){if(S[e.level]<S[this.minLevel])return;if(this.format==="json"){console.log(JSON.stringify(e));return}let t={debug:"\x1B[90m",info:"\x1B[34m",warn:"\x1B[33m",error:"\x1B[31m",fatal:"\x1B[35m"},n="\x1B[0m",s=t[e.level]??"",r=e.level.toUpperCase().padEnd(5),i=Object.keys(e.context).length>0?` ${JSON.stringify(e.context)}`:"",o=e.level==="error"||e.level==="fatal"?"error":"log";console[o](`${s}[${e.timestamp}] ${r}${n} ${e.message}${i}`)}},D=class{minLevel;path;format;initialized=!1;constructor(e){this.minLevel=e.level??"info",this.path=e.path??"storage/logs/app.log",this.format=e.format??"text"}async write(e){if(S[e.level]<S[this.minLevel])return;this.initialized||(await oe(ce(this.path),{recursive:!0}),this.initialized=!0);let t;if(this.format==="json")t=JSON.stringify(e)+`
+`;else{let n=e.level.toUpperCase().padEnd(5),s=Object.keys(e.context).length>0?` ${JSON.stringify(e.context)}`:"";t=`[${e.timestamp}] ${n} ${e.message}${s}
+`}await ae(this.path,t)}},M=class{minLevel="debug";channelNames;resolver;constructor(e,t){this.channelNames=e.channels??[],this.resolver=t,this.minLevel=e.level??"debug"}async write(e){for(let t of this.channelNames){let n=this.resolver(t);n&&await n.write(e)}}},_=class{minLevel="debug";write(){}},I=class{config={default:"console",channels:{console:{driver:"console",level:"debug"}}};channels=new Map;configure(e){this.config=e,this.channels.clear()}channel(e){return new U(this.resolveChannel(e))}debug(e,t={}){this.writeToDefault({level:"debug",message:e,context:t,timestamp:d()})}info(e,t={}){this.writeToDefault({level:"info",message:e,context:t,timestamp:d()})}warn(e,t={}){this.writeToDefault({level:"warn",message:e,context:t,timestamp:d()})}error(e,t={}){this.writeToDefault({level:"error",message:e,context:t,timestamp:d()})}fatal(e,t={}){this.writeToDefault({level:"fatal",message:e,context:t,timestamp:d()})}writeToDefault(e){this.resolveChannel(this.config.default).write(e)}resolveChannel(e){if(this.channels.has(e))return this.channels.get(e);let t=this.config.channels[e];if(!t){let s=new f({driver:"console"});return this.channels.set(e,s),s}let n=this.createChannel(t);return this.channels.set(e,n),n}createChannel(e){switch(e.driver){case"console":return new f(e);case"file":return new D(e);case"stack":return new M(e,t=>this.resolveChannel(t));case"null":return new _;default:return new f(e)}}},U=class{constructor(e){this.channel=e}debug(e,t={}){this.channel.write({level:"debug",message:e,context:t,timestamp:d()})}info(e,t={}){this.channel.write({level:"info",message:e,context:t,timestamp:d()})}warn(e,t={}){this.channel.write({level:"warn",message:e,context:t,timestamp:d()})}error(e,t={}){this.channel.write({level:"error",message:e,context:t,timestamp:d()})}fatal(e,t={}){this.channel.write({level:"fatal",message:e,context:t,timestamp:d()})}};function d(){return new Date().toISOString()}var Y=X("svelar.log",()=>new I);var h=class extends Error{constructor(t,n,s){super(n);this.statusCode=t;this.details=s;this.name="HttpError"}},$=class extends h{constructor(e="The requested resource was not found"){super(404,e),this.name="NotFoundError"}},H=class extends h{constructor(e="Unauthenticated"){super(401,e),this.name="UnauthorizedError"}},F=class extends h{constructor(e="You do not have permission to perform this action"){super(403,e),this.name="ForbiddenError"}},R=class extends h{constructor(t,n="The given data was invalid"){super(422,n,{errors:t});this.errors=t;this.name="ValidationError"}};var C=class{config;constructor(e={}){this.config={debug:process.env.NODE_ENV!=="production",dontReport:[R,$,H,F],...e}}async handle(e,t){let n=e instanceof Error?e:new Error(String(e));return await this.reportError(n,t),this.config.render?this.config.render(n,t):this.renderError(n)}handleSvelteKitError(){return({error:e,event:t,status:n,message:s})=>{let r=e instanceof Error?e:new Error(String(e));return this.reportError(r,t),r instanceof h?{message:r.message,status:r.statusCode,...r.details??{},...this.config.debug?{stack:r.stack}:{}}:{message:this.config.debug?r.message:"An unexpected error occurred",status:n,...this.config.debug?{stack:r.stack}:{}}}}middleware(){let e=this;return async(t,n)=>{try{return await n()}catch(s){return e.handle(s,t.event)}}}async reportError(e,t){if(this.config.dontReport){for(let s of this.config.dontReport)if(e instanceof s)return}let n={error:e.name,...t?.url?{url:t.url.toString()}:{},...e.stack?{stack:e.stack}:{}};if(Y.error(e.message,n),this.config.report)try{await this.config.report(e,t?{url:t.url?.toString()}:void 0)}catch{}}renderError(e){if(e instanceof h){let n={message:e.message};return e instanceof R&&(n.errors=e.errors),e.details&&Object.assign(n,e.details),this.config.debug&&(n.exception=e.name,n.stack=e.stack?.split(`
+`).map(s=>s.trim())),new Response(JSON.stringify(n),{status:e.statusCode,headers:{"Content-Type":"application/json"}})}let t={message:this.config.debug?e.message:"Internal server error"};return this.config.debug&&(t.exception=e.name,t.stack=e.stack?.split(`
+`).map(n=>n.trim())),new Response(JSON.stringify(t),{status:500,headers:{"Content-Type":"application/json"}})}};function $e(a={}){let{auth:e,secret:t=process.env.APP_KEY||(()=>{throw new Error("APP_KEY is not set. Set it in your .env file.")})(),sessionStore:n,sessionLifetime:s=86400,rateLimit:r=100,rateLimitWindow:i=6e4,csrfPaths:o=["/api/"],csrfExcludePaths:c=["/api/webhooks"],authThrottleAttempts:u=5,authThrottleDecay:N=1,debug:K=process.env.NODE_ENV!=="production",middleware:z=[],namedMiddleware:G={},i18n:q,errorConfig:Z={}}=a,A=[new v,new w({maxRequests:r,windowMs:i}),new y({onlyPaths:o,excludePaths:c}),new T({store:n??new g,secret:t,lifetime:s})];e&&A.push(new b(e)),A.push(...z);let Q={"auth-throttle":new E({maxAttempts:u,decayMinutes:N}),...G},j=new C({debug:K,...Z}),J=le({middleware:A,namedMiddleware:Q,onError:(k,O)=>j.handle(k,O)}),P;if(q){let{paraglideMiddleware:k,getTextDirection:O=()=>"ltr"}=q;P=de(async({event:L,resolve:ee})=>k(L.request,({request:te,locale:W})=>(L.request=te,ee(L,{transformPageChunk:({html:ne})=>ne.replace("%lang%",W).replace("%dir%",O(W))}))),J)}else P=J;return{handle:P,handleError:j.handleSvelteKitError()}}function le(a={}){let e=new m;if(a.middleware)for(let t of a.middleware)e.use(t);if(a.namedMiddleware)for(let[t,n]of Object.entries(a.namedMiddleware))e.register(t,n);return async function({event:n,resolve:s}){let r={event:n,params:n.params??{},locals:n.locals??{}};try{a.app&&!a.app.isBooted()&&await a.app.bootstrap();let i=await e.execute(r,async()=>s(n));return i instanceof Response?i:s(n)}catch(i){if(a.onError){let o=await a.onError(i,n);if(o instanceof Response)return o}return console.error("[Svelar] Unhandled error in hooks:",i),new Response(JSON.stringify({message:process.env.NODE_ENV==="production"?"Internal server error":i.message}),{status:500,headers:{"Content-Type":"application/json"}})}}}function de(...a){return async function({event:t,resolve:n}){let s=n;for(let r=a.length-1;r>=0;r--){let i=a[r],o=s;s=c=>i({event:c,resolve:o})}return s(t)}}export{$e as createSvelarApp,le as createSvelarHooks,de as sequence};

package/dist/http/index.d.ts

@@ -0,0 +1,201 @@
+/**
+ * Svelar HTTP Utilities
+ *
+ * Client-side: CSRF-aware fetch wrapper, automatic error toast handling.
+ * Server-side: Fluent HTTP client for third-party API calls (Postmark, Stripe, etc.)
+ *
+ * @module svelar/http
+ *
+ * @example
+ * ```ts
+ * // Client-side (browser)
+ * import { apiFetch } from '@beeblock/svelar/http';
+ * const res = await apiFetch('/api/posts', { method: 'POST', body: JSON.stringify({ title: 'Hello' }) });
+ *
+ * // Server-side (third-party APIs)
+ * import { Http } from '@beeblock/svelar/http';
+ * const response = await Http.withToken(POSTMARK_TOKEN)
+ *   .baseUrl('https://api.postmarkapp.com')
+ *   .post('/email', { From: 'hi@example.com', To: 'user@example.com', Subject: 'Hello' });
+ * ```
+ */
+export interface ApiFetchOptions extends RequestInit {
+    /** Custom CSRF cookie name (default: 'XSRF-TOKEN') */
+    csrfCookieName?: string;
+    /** Custom CSRF header name (default: 'X-CSRF-Token') */
+    csrfHeaderName?: string;
+    /** Show toast on error responses (default: true) */
+    showToast?: boolean;
+    /** Custom error messages by status code */
+    errorMessages?: Record<number, string>;
+}
+export interface ApiResponse<T = any> {
+    data: T | null;
+    error: ApiError | null;
+    status: number;
+    ok: boolean;
+    response: Response;
+}
+export interface ApiError {
+    message: string;
+    status: number;
+    errors?: Record<string, string[]>;
+    details?: Record<string, any>;
+}
+/**
+ * Register the toast function from the UI layer.
+ * Called automatically when <Toaster /> mounts.
+ * Can also be called manually for custom toast implementations.
+ */
+export declare function registerToast(fn: (variant: string, title: string, opts?: any) => void): void;
+/**
+ * CSRF-aware fetch wrapper with automatic error toast notifications.
+ *
+ * Features:
+ * - Attaches CSRF token from cookies on mutation requests
+ * - Shows toast notifications on error responses
+ * - Handles network errors gracefully
+ * - 401 responses can trigger redirect to login
+ *
+ * @example
+ * ```ts
+ * import { apiFetch } from 'svelar/http';
+ *
+ * // POST with auto error toast
+ * const res = await apiFetch('/api/posts', {
+ *   method: 'POST',
+ *   body: JSON.stringify({ title: 'Hello', body: 'World' }),
+ * });
+ *
+ * // Disable toast for manual error handling
+ * const res = await apiFetch('/api/users', { showToast: false });
+ *
+ * // Custom error message for specific status
+ * const res = await apiFetch('/api/billing', {
+ *   method: 'POST',
+ *   errorMessages: { 402: 'Payment required. Please update your billing.' },
+ * });
+ * ```
+ */
+export declare function apiFetch(url: string, options?: ApiFetchOptions): Promise<Response>;
+/**
+ * Typed JSON fetch — returns parsed data or error, never throws.
+ *
+ * @example
+ * ```ts
+ * import { apiFetchJson } from 'svelar/http';
+ *
+ * const { data, error, ok } = await apiFetchJson<User[]>('/api/users');
+ * if (ok) {
+ *   console.log(data); // User[]
+ * } else {
+ *   console.log(error); // ApiError
+ * }
+ * ```
+ */
+export declare function apiFetchJson<T = any>(url: string, options?: ApiFetchOptions): Promise<ApiResponse<T>>;
+/**
+ * Extract a cookie value by name from document.cookie.
+ */
+export declare function getCsrfToken(cookieName?: string): string | null;
+/**
+ * Fetch wrapper that signs requests with HMAC-SHA256.
+ * Use with SignatureMiddleware on the server.
+ *
+ * @example
+ * ```ts
+ * import { signedFetch } from 'svelar/http';
+ *
+ * const res = await signedFetch('/api/webhooks', {
+ *   method: 'POST',
+ *   body: JSON.stringify({ event: 'order.created' }),
+ *   signingSecret: 'your-shared-secret',
+ * });
+ * ```
+ */
+export declare function signedFetch(url: string, options: ApiFetchOptions & {
+    signingSecret: string;
+    signatureHeader?: string;
+    timestampHeader?: string;
+}): Promise<Response>;
+/**
+ * Build a URL with query parameters.
+ *
+ * @example
+ * ```ts
+ * buildUrl('/api/posts', { page: 1, per_page: 10 });
+ * // => '/api/posts?page=1&per_page=10'
+ * ```
+ */
+export declare function buildUrl(base: string, params?: Record<string, string | number | boolean | undefined | null>): string;
+export interface HttpClientResponse<T = any> {
+    data: T;
+    status: number;
+    headers: Headers;
+    ok: boolean;
+}
+export interface HttpClientConfig {
+    baseUrl?: string;
+    headers?: Record<string, string>;
+    timeout?: number;
+    retries?: number;
+    retryDelay?: number;
+}
+export declare class HttpClient {
+    private _baseUrl;
+    private _headers;
+    private _timeout;
+    private _retries;
+    private _retryDelay;
+    private _query;
+    constructor(config?: HttpClientConfig);
+    private clone;
+    baseUrl(url: string): HttpClient;
+    withHeaders(headers: Record<string, string>): HttpClient;
+    withToken(token: string, type?: 'Bearer' | string): HttpClient;
+    withBasicAuth(username: string, password: string): HttpClient;
+    accept(contentType: string): HttpClient;
+    contentType(type: string): HttpClient;
+    timeout(ms: number): HttpClient;
+    retry(times: number, delayMs?: number): HttpClient;
+    query(params: Record<string, string | number | boolean | undefined | null>): HttpClient;
+    get<T = any>(path: string): Promise<HttpClientResponse<T>>;
+    post<T = any>(path: string, body?: unknown): Promise<HttpClientResponse<T>>;
+    put<T = any>(path: string, body?: unknown): Promise<HttpClientResponse<T>>;
+    patch<T = any>(path: string, body?: unknown): Promise<HttpClientResponse<T>>;
+    delete<T = any>(path: string, body?: unknown): Promise<HttpClientResponse<T>>;
+    private request;
+    private buildFullUrl;
+}
+export declare class HttpRequestError extends Error {
+    readonly status: number;
+    readonly body: any;
+    constructor(message: string, status: number, body: any);
+}
+/**
+ * Server-side HTTP client factory.
+ * Returns a new HttpClient instance for making authenticated API calls to third-party services.
+ *
+ * @example
+ * ```ts
+ * import { Http } from '@beeblock/svelar/http';
+ *
+ * // Postmark
+ * const res = await Http.withToken(POSTMARK_TOKEN, 'X-Postmark-Server-Token')
+ *   .baseUrl('https://api.postmarkapp.com')
+ *   .post('/email', { From: 'hi@example.com', To: 'user@example.com' });
+ *
+ * // Stripe
+ * const res = await Http.withToken(STRIPE_SECRET)
+ *   .baseUrl('https://api.stripe.com/v1')
+ *   .contentType('application/x-www-form-urlencoded')
+ *   .post('/customers', 'email=user@example.com');
+ *
+ * // Custom header auth
+ * const res = await Http.withHeaders({ 'X-API-Key': API_KEY })
+ *   .baseUrl('https://api.mailchimp.com/3.0')
+ *   .retry(3)
+ *   .get('/lists');
+ * ```
+ */
+export declare const Http: HttpClient;

package/dist/http/index.js

@@ -0,0 +1,2 @@
+var T={400:"Invalid request. Please check your input.",401:"Your session has expired. Please sign in again.",403:"You don't have permission to do this.",404:"The requested resource was not found.",405:"This action is not allowed.",409:"A conflict occurred. Please refresh and try again.",419:"Page expired. Please refresh and try again.",422:"The submitted data is invalid.",429:"Too many requests. Please wait a moment.",500:"Something went wrong on our end.",502:"Service temporarily unavailable. Try again shortly.",503:"Service is under maintenance. Try again shortly.",504:"Request timed out. Please try again."},w=null;function P(s){w=s}function g(s,t,e){w&&w(s,t,{description:e})}async function R(s,t={}){let{csrfCookieName:e="XSRF-TOKEN",csrfHeaderName:r="X-CSRF-Token",showToast:n=!0,errorMessages:c={},...i}=t,p=(i.method||"GET").toUpperCase(),u=new Headers(i.headers);if(["POST","PUT","PATCH","DELETE"].includes(p)){let o=A(e);o&&u.set(r,o)}i.body&&typeof i.body=="string"&&!u.has("Content-Type")&&u.set("Content-Type","application/json"),u.has("Accept")||u.set("Accept","application/json");try{let o=await fetch(s,{...i,headers:u});return!o.ok&&n&&await E(o,{...T,...c}),o}catch(o){throw n&&g("error","Network Error","Unable to connect. Check your internet connection."),o}}async function x(s,t={}){try{let e=await R(s,t),r=null,n=null;if((e.headers.get("content-type")??"").includes("application/json")){let i=await e.json();e.ok?r=i:n={message:i.message??T[e.status]??"An error occurred",status:e.status,errors:i.errors,details:i}}else e.ok?r=await e.text():n={message:T[e.status]??`Error ${e.status}`,status:e.status};return{data:r,error:n,status:e.status,ok:e.ok,response:e}}catch(e){return{data:null,error:{message:e.message??"Network error",status:0},status:0,ok:!1,response:new Response(null,{status:0})}}}async function E(s,t){let e="";try{if((s.headers.get("content-type")??"").includes("application/json")){let i=await s.clone().json();if(e=i.message??"",s.status===422&&i.errors){let p=Object.entries(i.errors).map(([u,o])=>`${u}: ${o.join(", ")}`).slice(0,3).join(`
+`);g("warning",t[422]??"Validation Error",p);return}}}catch{}let r=e||t[s.status]||`Error ${s.status}`,n=s.status>=500?"error":s.status===429?"warning":"error";if(s.status===401){g("warning",r,"Please sign in to continue.");return}g(n,r)}function A(s="XSRF-TOKEN"){if(typeof document>"u")return null;let t=s.replace(/[.*+?^${}()|[\]\\]/g,"\\$&"),e=document.cookie.match(new RegExp(`(?:^|;\\s*)${t}=([^;]*)`));return e?decodeURIComponent(e[1]):null}async function U(s,t){let{signingSecret:e,signatureHeader:r="X-Signature",timestampHeader:n="X-Timestamp",...c}=t,i=(c.method||"GET").toUpperCase(),p=typeof c.body=="string"?c.body:"",u=Math.floor(Date.now()/1e3),o=new URL(s,"http://localhost"),l=o.pathname+o.search,y=`${u}.${i}.${l}.${p}`,a=new TextEncoder,m=a.encode(e),d=a.encode(y),H=await crypto.subtle.importKey("raw",m,{name:"HMAC",hash:"SHA-256"},!1,["sign"]),_=await crypto.subtle.sign("HMAC",H,d),C=Array.from(new Uint8Array(_),k=>k.toString(16).padStart(2,"0")).join(""),f=new Headers(c.headers);return f.set(r,C),f.set(n,String(u)),R(s,{...c,headers:f,method:i})}function v(s,t){if(!t)return s;let e=new URL(s,"http://localhost");for(let[r,n]of Object.entries(t))n!=null&&e.searchParams.set(r,String(n));return e.pathname+e.search}var b=class s{_baseUrl="";_headers={};_timeout=3e4;_retries=0;_retryDelay=1e3;_query={};constructor(t){t?.baseUrl&&(this._baseUrl=t.baseUrl),t?.headers&&(this._headers={...t.headers}),t?.timeout&&(this._timeout=t.timeout),t?.retries&&(this._retries=t.retries),t?.retryDelay&&(this._retryDelay=t.retryDelay)}clone(){let t=new s;return t._baseUrl=this._baseUrl,t._headers={...this._headers},t._timeout=this._timeout,t._retries=this._retries,t._retryDelay=this._retryDelay,t._query={...this._query},t}baseUrl(t){let e=this.clone();return e._baseUrl=t,e}withHeaders(t){let e=this.clone();return e._headers={...e._headers,...t},e}withToken(t,e="Bearer"){return this.withHeaders({Authorization:`${e} ${t}`})}withBasicAuth(t,e){let r=Buffer.from(`${t}:${e}`).toString("base64");return this.withHeaders({Authorization:`Basic ${r}`})}accept(t){return this.withHeaders({Accept:t})}contentType(t){return this.withHeaders({"Content-Type":t})}timeout(t){let e=this.clone();return e._timeout=t,e}retry(t,e=1e3){let r=this.clone();return r._retries=t,r._retryDelay=e,r}query(t){let e=this.clone();for(let[r,n]of Object.entries(t))n!=null&&(e._query[r]=String(n));return e}async get(t){return this.request("GET",t)}async post(t,e){return this.request("POST",t,e)}async put(t,e){return this.request("PUT",t,e)}async patch(t,e){return this.request("PATCH",t,e)}async delete(t,e){return this.request("DELETE",t,e)}async request(t,e,r){let n=this.buildFullUrl(e),c={...this._headers},i;r!==void 0&&(c["Content-Type"]||(c["Content-Type"]="application/json"),i=typeof r=="string"?r:JSON.stringify(r)),c.Accept||(c.Accept="application/json");let p=null,u=1+this._retries;for(let o=0;o<u;o++){o>0&&await new Promise(l=>setTimeout(l,this._retryDelay*o));try{let l=new AbortController,y=setTimeout(()=>l.abort(),this._timeout),a=await fetch(n,{method:t,headers:c,body:i,signal:l.signal});if(clearTimeout(y),!a.ok&&a.status<500&&o<u-1,!a.ok&&a.status>=500&&o<u-1){p=new h(`HTTP ${a.status}: ${a.statusText}`,a.status,await a.text());continue}let m=a.headers.get("content-type")??"",d;if(m.includes("application/json")?d=await a.json():d=await a.text(),!a.ok)throw new h(`HTTP ${a.status}: ${typeof d=="string"?d:JSON.stringify(d)}`,a.status,d);return{data:d,status:a.status,headers:a.headers,ok:!0}}catch(l){if(l instanceof h)throw l;if(p=l,l.name==="AbortError"&&(p=new h("Request timed out",0,null)),o>=u-1)break}}throw p??new Error("HTTP request failed")}buildFullUrl(t){let e=this._baseUrl?`${this._baseUrl.replace(/\/+$/,"")}/${t.replace(/^\/+/,"")}`:t,r=Object.entries(this._query);if(r.length>0){let n=new URL(e);for(let[c,i]of r)n.searchParams.set(c,i);e=n.toString()}return e}},h=class extends Error{constructor(e,r,n){super(e);this.status=r;this.body=n;this.name="HttpRequestError"}},S=new b;export{S as Http,b as HttpClient,h as HttpRequestError,R as apiFetch,x as apiFetchJson,v as buildUrl,A as getCsrfToken,P as registerToast,U as signedFetch};

package/dist/i18n/index.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Svelar i18n Integration
+ *
+ * Helpers for integrating paraglide-js 2.x with SvelteKit.
+ * Provides middleware composers, reroute hook creators, and the LanguageSwitcher component.
+ *
+ * @module svelar/i18n
+ *
+ * @example
+ * ```ts
+ * // hooks.server.ts
+ * import { createI18nHandle } from 'svelar/i18n';
+ * import { paraglideMiddleware } from '$lib/paraglide/server';
+ * import { getTextDirection } from '$lib/paraglide/runtime';
+ *
+ * const i18nHandle = createI18nHandle({ paraglideMiddleware, getTextDirection });
+ * ```
+ */
+import type { Handle } from '@sveltejs/kit';
+export interface I18nHandleConfig {
+    /**
+     * The paraglide middleware function from `$lib/paraglide/server`.
+     * Signature: (request, callback) => Response
+     */
+    paraglideMiddleware: (request: Request, callback: (args: {
+        request: Request;
+        locale: string;
+    }) => Response | Promise<Response>) => Response | Promise<Response>;
+    /**
+     * The getTextDirection function from `$lib/paraglide/runtime`.
+     * Returns 'ltr' or 'rtl' for a given locale.
+     */
+    getTextDirection?: (locale: string) => string;
+    /**
+     * HTML lang attribute placeholder (default: '%lang%')
+     */
+    langPlaceholder?: string;
+    /**
+     * HTML dir attribute placeholder (default: '%dir%')
+     */
+    dirPlaceholder?: string;
+}
+export interface RerouteConfig {
+    /**
+     * The deLocalizeUrl function from `$lib/paraglide/runtime`.
+     * Strips the locale prefix from URLs for SvelteKit routing.
+     */
+    deLocalizeUrl: (url: URL) => {
+        pathname: string;
+    };
+}
+/**
+ * Creates a SvelteKit `Handle` hook that wires paraglide-js middleware
+ * for server-side locale detection and HTML attribute injection.
+ *
+ * @example
+ * ```ts
+ * import { createI18nHandle } from 'svelar/i18n';
+ * import { paraglideMiddleware } from '$lib/paraglide/server';
+ * import { getTextDirection } from '$lib/paraglide/runtime';
+ *
+ * export const i18nHandle = createI18nHandle({ paraglideMiddleware, getTextDirection });
+ * ```
+ */
+export declare function createI18nHandle(config: I18nHandleConfig): Handle;
+/**
+ * Creates a SvelteKit `Reroute` function that strips locale prefixes
+ * from URLs so SvelteKit's file-based routing works correctly.
+ *
+ * @example
+ * ```ts
+ * // hooks.ts (client-side)
+ * import { createReroute } from 'svelar/i18n';
+ * import { deLocalizeUrl } from '$lib/paraglide/runtime';
+ *
+ * export const reroute = createReroute({ deLocalizeUrl });
+ * ```
+ */
+export declare function createReroute(config: RerouteConfig): (request: {
+    url: URL;
+}) => string;

package/dist/i18n/index.js

@@ -0,0 +1 @@
+function d(e){let{paraglideMiddleware:r,getTextDirection:a=()=>"ltr",langPlaceholder:l="%lang%",dirPlaceholder:o="%dir%"}=e;return({event:t,resolve:i})=>r(t.request,({request:s,locale:n})=>(t.request=s,i(t,{transformPageChunk:({html:c})=>c.replace(l,n).replace(o,a(n))})))}function u(e){return r=>e.deLocalizeUrl(r.url).pathname}export{d as createI18nHandle,u as createReroute};

package/dist/index.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Svelar — Laravel-inspired framework on top of SvelteKit 2
+ *
+ * @module svelar
+ */
+export { Model, type ModelAttributes, type ModelHooks } from './orm/Model.js';
+export { QueryBuilder } from './orm/QueryBuilder.js';
+export { HasOne, HasMany, BelongsTo, BelongsToMany } from './orm/Relationship.js';
+export { Connection, type DatabaseConfig, type DatabaseDriver, type ConnectionsConfig } from './database/Connection.js';
+export { Schema, schema, TableBuilder, ColumnBuilder } from './database/SchemaBuilder.js';
+export { Migration, Migrator } from './database/Migration.js';
+export { Seeder } from './database/Seeder.js';
+export { Container, container } from './container/Container.js';
+export { ServiceProvider } from './container/ServiceProvider.js';
+export { Application } from './container/Application.js';
+export { Middleware, MiddlewareStack, CorsMiddleware, RateLimitMiddleware, LoggingMiddleware, CsrfMiddleware, OriginMiddleware, ThrottleMiddleware, SignatureMiddleware } from './middleware/Middleware.js';
+export type { MiddlewareContext, NextFunction, MiddlewareHandler } from './middleware/Middleware.js';
+export { Controller, resource, ValidationError, NotFoundError, UnauthorizedError, ForbiddenError } from './routing/Controller.js';
+export type { RequestEvent } from './routing/Controller.js';
+export { createSvelarHooks, sequence } from './hooks/index.js';
+export { config, env } from './config/Config.js';
+export { z, rules, validate } from './validation/index.js';
+export { AuthManager, AuthenticateMiddleware, RequireAuthMiddleware, signJwt, verifyJwt } from './auth/Auth.js';
+export type { AuthConfig, AuthUser, GuardType, JwtConfig, JwtPayload } from './auth/Auth.js';
+export { Hash } from './hashing/Hash.js';
+export type { HashDriver, HashConfig } from './hashing/Hash.js';
+export { Session, SessionMiddleware, MemorySessionStore, DatabaseSessionStore, FileSessionStore, RedisSessionStore } from './session/Session.js';
+export type { SessionStore, SessionConfig, SessionData } from './session/Session.js';
+export { ErrorHandler, HttpError, abort, abortIf, abortUnless, ModelNotFoundError } from './errors/Handler.js';
+export type { ErrorHandlerConfig } from './errors/Handler.js';
+export { Event, EventDispatcher } from './events/index.js';
+export type { EventClass, EventListener, Subscriber } from './events/index.js';
+export { FormRequest, FormValidationError, FormAuthorizationError } from './routing/FormRequest.js';
+export { Storage } from './storage/index.js';
+export type { StorageConfig, DiskConfig, FileInfo } from './storage/index.js';
+export { Log } from './logging/index.js';
+export type { LogLevel, LogConfig, LogChannelConfig } from './logging/index.js';
+export { Cache } from './cache/index.js';
+export type { CacheConfig, CacheStoreConfig, CacheDriver } from './cache/index.js';
+export { Queue, Job } from './queue/index.js';
+export type { QueueConfig, DispatchOptions } from './queue/index.js';
+export { Mailer, Mailable } from './mail/index.js';
+export type { MailerConfig, MailMessage, SendResult } from './mail/index.js';
+export { Notifier, Notification } from './notifications/index.js';
+export type { Notifiable, NotificationChannel } from './notifications/index.js';
+export { Broadcast } from './broadcasting/index.js';
+export { apiFetch, getCsrfToken, buildUrl } from './http/index.js';
+export type { ApiFetchOptions } from './http/index.js';
+export { createI18nHandle, createReroute } from './i18n/index.js';
+export type { I18nHandleConfig, RerouteConfig } from './i18n/index.js';
+export { createFormAction, loadForm, validateForm } from './forms/index.js';
+export type { FormActionOptions } from './forms/index.js';
+export { createSvelarApp } from './hooks/index.js';
+export type { SvelarAppConfig } from './hooks/index.js';