network_api_sdk 0.1.2

A Flutter networking SDK for API communication, authentication, interceptors, caching, and offline queue handling.

Network API SDK

A production-ready Flutter networking SDK with built-in authentication, interceptors, offline caching, and request queueing — designed for scalable and enterprise-grade applications.

---

🤖 SDK AI Assistant

Get instant help integrating the SDK using the official AI assistant.

It can:

• Generate ready-to-use integration code
• Explain authentication flows
• Debug API issues
• Guide offline and queue behavior

Assistant:

https://chatgpt.com/g/g-69aa3c19d9e081918dafe44ed385559c-network-api-sdk-guide

---

Table of Contents

1. Overview
2. Public API Surface
3. Installation
4. Importing SDK
5. Architecture
6. Quick Start
7. SDK Initialization
8. SdkConfig Reference
9. SdkProfile Reference
10. SdkContract Reference
11. OutputOptions Reference
12. AuthOptions Reference
13. HTTP Calls
14. RequestBody Types
15. Authentication
16. Interceptors
17. Response Model
18. Error Model
19. Events
20. Offline Support
21. Persistence Stores
22. HTTP Extension Points
23. Example Project
24. Advanced Initialization
25. Flow Diagrams
26. Troubleshooting
27. Project Status

---

1. Overview

Network API SDK is a standardized networking layer for Flutter applications.

It centralizes:

• request construction
• response normalization
• contract-based success/error evaluation
• authentication lifecycle
• interceptor execution
• offline caching
• offline request queue
• persistent request queue
• queue flushing

The goal is to make API integration consistent across applications.

❓ Why Network API SDK?

• Eliminates repetitive API boilerplate
• Standardizes authentication and error handling
• Provides built-in offline support and persistence
• Ensures consistent API contracts across applications
• Designed for enterprise-scale Flutter projects

---

2. Public API Surface

Core

• Sdk
• SdkEvents
• SdkEvent

Configuration

• SdkConfig
• SdkProfile
• SdkContract
• OutputOptions
• AuthOptions

Models

• RequestBody
• BodyFile
• BodyType
• ResponseTypeHint
• SdkResponse
• SdkError
• ResponseSource
• ErrorType

Authentication

• AuthManager
• TokenStore
• SecureTokenStore

Interceptors

• SdkInterceptor

HTTP Layer

• HttpClient
• HttpRequest
• HttpResponse
• DioHttpClient

Offline Layer

• CacheStore
• FileCacheStore
• QueueStore
• FileQueueStore

---

3. Installation

Local dependency

dependencies:
  network_api_sdk:
    path: ../network_api_sdk

Published dependency

dependencies:
  network_api_sdk: ^0.1.0

Run:

flutter pub get

---

4. Importing SDK

import 'package:network_api_sdk/network_api_sdk.dart';

Always import from the package root.

Avoid importing from src.

---

5. Architecture

SDK architecture layers:

Application Layer
        ↓
     SDK Core
        ↓
     HTTP Layer
        ↓
    Storage Layer

SDK Core Responsibilities

• Request building
• Response normalization
• Authentication lifecycle
• Contract evaluation
• Interceptors
• Offline orchestration

---

6. Quick Start

⚡ 30-Second Setup

Sdk.init(
  SdkConfig(
    baseUrl: 'https://api.example.com',
    profile: SdkProfile.defaultSecure(),
    contract: SdkContract.auto(
      data: 'data',
      message: 'message',
      successFlag: 'isSuccess',
      errorCode: 'code',
    ),
    output: OutputOptions.jsonOnly(),
  ),
);

final res = await Sdk.instance.call.get('/users');

Initialize the SDK:

Sdk.init(
  SdkConfig(
    baseUrl: 'https://api.example.com',
    profile: SdkProfile.defaultSecure(),
    contract: SdkContract.auto(
      data: 'data',
      message: 'message',
      successFlag: 'isSuccess',
      errorCode: 'code',
    ),
    output: OutputOptions.jsonOnly(),
  ),
);

Example usage:

final response = await Sdk.instance.call.get('/profile');

---

7. SDK Initialization

Initialize once:

Sdk.init(SdkConfig(...));

Access instance:

Sdk.instance

Available modules:

• Sdk.instance.call
• Sdk.instance.auth
• Sdk.instance.events
• Sdk.instance.http
• Sdk.instance.cache
• Sdk.instance.queue
• Sdk.instance.config

---

8. SdkConfig Reference

Primary SDK configuration.

Example:

SdkConfig(
  baseUrl: 'https://api.example.com',
  profile: SdkProfile.defaultSecure(),
  contract: SdkContract.auto(
    data: 'data',
    message: 'message',
  ),
  output: OutputOptions.jsonOnly(),
)

Parameter	Type	Required	Description
baseUrl	String	Yes	API base URL
httpOverride	HttpClient?	No	Custom HTTP client
auth	AuthOptions?	No	Authentication configuration
tokenStoreOverride	TokenStore?	No	Custom token storage
cacheStoreOverride	CacheStore?	No	Custom cache store
queueStoreOverride	QueueStore?	No	Custom queue store
profile	SdkProfile	Yes	Offline configuration
contract	SdkContract	Yes	API contract
output	OutputOptions	Yes	Response normalization
interceptors	List<SdkInterceptor>?	No	SDK interceptors

---

9. SdkProfile Reference

Controls offline behavior.

const SdkProfile(
  offlineEnabled: true,
  queueWritesWhenOffline: true,
  autoFlushQueue: true,
  flushInterval: null,
)

Field	Type	Description
offlineEnabled	bool	Enable offline features
queueWritesWhenOffline	bool	Queue writes when offline
autoFlushQueue	bool	Flush the queue once on init when flushInterval is null
flushInterval	Duration?	Reserved for future scheduled flushing; not used by the built-in flow yet

Factories:

SdkProfile.defaultSecure();
SdkProfile.offlineFirstSecure();

---

10. SdkContract Reference

Defines backend response structure.

SdkContract.auto(
  data: 'data',
  message: 'message',
  successFlag: 'isSuccess',
  errorCode: 'code',
)

Fallback error path:

errors[0].message

---

11. OutputOptions Reference

Controls SDK output format.

OutputOptions.jsonOnly();

Advanced:

OutputOptions.jsonOnly(
  tryParseJsonText: true,
  bytesMode: BytesJsonMode.base64,
);

---

12. AuthOptions Reference

AuthOptions(
  loginEndpoint: '/auth/login',
  refreshEndpoint: '/auth/refresh',
  accessTokenPath: 'accessToken',
  refreshTokenPath: 'refreshToken',
);

Field	Type	Description
loginEndpoint	String	Login API
refreshEndpoint	String	Refresh API
accessTokenPath	String	Access token path
refreshTokenPath	String	Refresh token path
refreshRequestKey	String	Refresh body key, defaults to refreshToken

---

13. HTTP Calls

Main entry:

Sdk.instance.call

Methods:

• get
• post
• put
• delete
• any

Example:

final res = await Sdk.instance.call.get('/users');

HTTP Call Parameters

Parameter	Type	Required	Description
endpoint	String	Yes	API endpoint path
query	Map<String, dynamic>?	No	Query parameters
headers	Map<String, String>?	No	Request headers
body	RequestBody?	No	Request payload
responseType	ResponseTypeHint?	No	Expected response type
attachAuth	bool	No	Whether to attach bearer token

---

14. RequestBody Types

Constructors:

RequestBody.none()
RequestBody.json()
RequestBody.text()
RequestBody.bytes()
RequestBody.formUrlEncoded()
RequestBody.multipart()

Example:

RequestBody.json({
  'email': '[e-mail]',
});

BodyFile

Used in multipart uploads.

Field	Type	Description
filename	String	File name
bytes	Uint8List	File data
contentType	String?	MIME type

---

15. Authentication

Login example:

await Sdk.instance.auth.login(
  body: {
    'username': 'user',
    'password': 'password',
  },
  rememberMe: true,
);

Login parameters

Parameter	Type	Description
body	Map	Login payload
headers	Map?	Extra headers
rememberMe	bool	Persist tokens

Sign Out

await Sdk.instance.auth.signOut();

---

16. Interceptors

Example:

class MyInterceptor implements SdkInterceptor {
  @override
  Future<HttpRequest?> onRequest(HttpRequest req) async => req;

  @override
  Future<HttpResponse?> onResponse(HttpRequest req, HttpResponse res) async => res;

  @override
  Future<SdkError?> onError(HttpRequest req, SdkError error) async => error;
}

Register:

interceptors: [
  MyInterceptor(),
]

---

17. Response Model

SDK responses return SdkResponse.

Example:

if (res.ok) {
  print(res.data);
}

Field	Type
ok	bool
data	dynamic
error	SdkError?
statusCode	int
message	String?
source	ResponseSource

ResponseSource

• network
• cache
• queued

---

18. Error Model

SDK errors return SdkError.

Field	Type
type	ErrorType
message	String
statusCode	int?
raw	dynamic

ErrorType

• offline
• timeout
• unauthorized
• forbidden
• badRequest
• server
• contract
• parse
• unknown

---

19. Events

Listen:

Sdk.instance.events.stream.listen((event) {
  // handle event
});

Events:

• sessionExpired
• signedOut

---

20. Offline Support

When enabled:

• GET → cache fallback
• WRITE → queued request

Manual queue flush:

await Sdk.instance.queue.flush();

---

21. Persistence Stores

Tokens

• TokenStore
• SecureTokenStore

Cache

• CacheStore
• FileCacheStore

Queue

• QueueStore
• FileQueueStore

---

22. HTTP Extension Points

Default client:

DioHttpClient

Constructor:

DioHttpClient(
  baseUrl: 'https://api.example.com',
  connectTimeout: Duration(seconds: 20),
  receiveTimeout: Duration(seconds: 30),
);

---

23. Example Project

Located in:

/example

Run:

cd example
flutter pub get
flutter run

---

24. Advanced Initialization

Offline-first configuration:

Sdk.init(
  SdkConfig(
    baseUrl: 'https://api.example.com',
    profile: SdkProfile.offlineFirstSecure(),
    contract: SdkContract.auto(
      data: 'data',
      message: 'message',
    ),
    output: OutputOptions.jsonOnly(),
  ),
);

---

25. Flow Diagrams

Authentication flow:

Login
 ↓
Save Tokens
 ↓
Attach Bearer
 ↓
401
 ↓
Refresh
 ↓
Retry Request

Offline queue flow:

Write Request
 ↓
No Internet
 ↓
Queue
 ↓
Persist
 ↓
Flush Later

---

26. Troubleshooting

SDK not initialized:

Sdk.init(
  SdkConfig(
    baseUrl: 'https://api.example.com',
    profile: SdkProfile.defaultSecure(),
    contract: SdkContract.auto(
      data: 'data',
      message: 'message',
    ),
    output: OutputOptions.jsonOnly(),
  ),
);

Refresh token failing:

Check:

• refreshEndpoint
• refreshTokenPath
• accessTokenPath

---

27. Project Status

Implemented

• SDK initialization
• contract parsing
• authentication login
• refresh token
• bearer token attach
• interceptors
• offline cache
• offline queue
• queue persistence
• manual queue flush
• auto flush on init
• SDK events

Planned

• retry policies
• observability
• upload progress
• cache invalidation
• advanced queue policies